Crate wasm4pm_compat

Expand description

§wasm4pm-compat

A nightly-only, paper-complete, structure-only Rust process-evidence standard.

Start with compatibility. Graduate to execution.

§Nightly requirement

This crate requires nightly Rust unconditionally. The rust-toolchain.toml pins the toolchain to nightly. The following features are declared at the crate root with no cfg gate:

generic_const_exprs — law machinery and WfNetConst<SOUNDNESS>
adt_const_params — ConditionCell<BITS>, Between01<NUM,DEN>, and Metric<KIND,NUM,DEN>
const_trait_impl — compile-time trait dispatch in law surfaces
min_specialization — type-law narrowing in nightly_foundry
portable_simd — SIMD-width type-law surface in nightly_foundry

There is no stable build target and no MSRV. Applications must conform upward to the type law, not the other way around.

§What this crate IS

A structure-only standard: the shape of process evidence and the laws of admission, refusal, and lossy projection.
A boundary layer: external formats are admitted into typed compat values, then exported back out (or graduated to wasm4pm) — never laundered raw-to-raw.
A place where refusal is first-class: every serious surface refuses with a specific named law (e.g. DanglingEventObjectLink, MissingFinalMarking, UnsoundWfNet), never a bare InvalidInput.
Built from small, transparent, strongly-named types: PhantomData witness/state markers and zero-cost #[repr(transparent)] ID wrappers.

§What this crate is NOT

Not a lite version of wasm4pm. It contains no engines: no discovery, no conformance checking, no replay, no alignment, no optimization, no visualization.
Not a data-laundering tool. Lossy projection always requires a named projection, a crate::loss::LossPolicy, a crate::loss::LossReport, and a refusal path.

§The one-way door

The central invariant is a typed, one-way lifecycle enforced by the type system:

Raw ──parse──▶ Parsed ──admit──▶ Admitted ──▶ {Projected | Exportable | Receipted}
  │                                  ▲
  └────────────── refuse ────────────┴──▶ Refused  (terminal; carries a named law)

Evidence<T, State, W> is the universal carrier. State and W are zero-sized PhantomData tags — zero runtime cost. Evidence<T, Raw, W> and Evidence<T, Admitted, W> are different types. A function demanding admitted evidence cannot be called with raw evidence. The Admitted constructor is pub(crate) — the only public path to admitted evidence is crate::admission::Admit::admit.

§Feature model

The public feature surface is exactly three. They control capability stages, not canon knowledge — the base profile already knows every shape.

Feature	Default	Meaning
`formats`	yes	import/export contracts, round-trip claims, loss surfaces
`strict`	no	opt-in boundary judgment: strict admission/refusal surfaces
`wasm4pm`	no	graduation bridge traits toward the `wasm4pm` execution engine

There are no per-format flags (no ocel/xes/bpmn/…). Nightly is not a Cargo feature: the crate requires nightly unconditionally. nightly_foundry.rs is a staging module that is always on.

§Test surfaces

Three distinct surfaces with different purposes and cadences:

Fast loop — cargo test --all-features --tests: unit and integration tests; sub-second after the initial build. Run on every change.
ALIVE gate — cargo test --test ui_tests -- --ignored: trybuild compile-fail and compile-pass fixtures that certify the type law. Explicit opt-in; ~4 min cold. A compile-fail fixture failing for the wrong reason is not a valid type-law receipt.
Documentation audit — cargo test --doc --all-features: verifies every public doctest compiles. Explicit opt-in; slow on nightly (each doctest touching nightly features is a separate rustc invocation).

Doctests are disabled in the default test run (doctest = false in Cargo.toml) to keep the dev loop fast.

§Adoption example

Build the core event-log shape via the crate::prelude:

use wasm4pm_compat::prelude::*;

// Build a single event, fold it into a trace, and a trace into a log.
let event = Event::new("place_order");
let trace = Trace::from_events([event]);
let log = EventLog::from_traces([trace]);
assert_eq!(log.trace_count(), 1);

The full Raw → Admitted path:

use wasm4pm_compat::admission::{Admit, Admission, Refusal};
use wasm4pm_compat::evidence::Evidence;
use wasm4pm_compat::state::Raw;
use wasm4pm_compat::witness::Ocel20;

enum LinkedOcel {}

impl Admit for LinkedOcel {
    type Raw = bool;
    type Admitted = bool;
    type Reason = &'static str;
    type Witness = Ocel20;
    fn admit(raw: Evidence<bool, Raw, Ocel20>)
        -> Result<Admission<bool, Ocel20>, Refusal<&'static str, Ocel20>>
    {
        if raw.value { Ok(Admission::new(true)) }
        else { Err(Refusal::new("DanglingEventObjectLink")) }
    }
}

let admitted = LinkedOcel::admit(Evidence::raw(true)).unwrap().into_evidence();
let exportable = admitted.into_exportable();
assert_eq!(exportable.value, true);

Examples are ignored here; see the examples/ directory for runnable walkthroughs of each capability stage.

§Graduation path

When you need to run something — discover a model, check conformance, replay a log — you graduate. With the wasm4pm feature, bridge traits hand your typed compat evidence to the execution engine. The compat crate stays structure-only; the engine does the work.

Re-exports§

pub use crate::admission::Admission;
pub use crate::admission::Admit;
pub use crate::admission::Refusal;
pub use crate::dfg::DfgMiner;
pub use crate::dfg::DirectlyFollowsGraph;
pub use crate::eventlog::Event;
pub use crate::eventlog::EventLog;
pub use crate::eventlog::EventLogClassifier;
pub use crate::eventlog::Trace;
pub use crate::evidence::Evidence;
pub use crate::ids::ActivityId;
pub use crate::ids::CaseId;
pub use crate::ids::EventId;
pub use crate::ids::ObjectId;
pub use crate::loss::LossPolicy;
pub use crate::loss::ProjectionName;
pub use crate::ocel::OcelLog;
pub use crate::petri::PetriNet;
pub use crate::petri::PetriNetBuilder;
pub use crate::petri::WfNet;
pub use crate::petri::WfNetConst;
pub use crate::powl8_op::Powl8Op;
pub use crate::powl8_op::Powl8OpError;
pub use crate::receipt::Blake3Hash;
pub use crate::receipt::ProvenanceChain;
pub use crate::receipt::ReceiptEnvelope;
pub use crate::state::Admitted;
pub use crate::state::Exportable;
pub use crate::state::Parsed;
pub use crate::state::Projected;
pub use crate::state::Raw;
pub use crate::state::Receipted;
pub use crate::state::Refused;
pub use crate::streaming::OfflineEvidence;
pub use crate::streaming::OnlineEvidence;
pub use crate::workflow::BranchToken;
pub use crate::workflow::Canceled;
pub use crate::workflow::Completed;
pub use crate::workflow::CompletedWorkflow;
pub use crate::workflow::JoinPoint;
pub use crate::workflow::ParallelWorkflow;
pub use crate::workflow::Pending;
pub use crate::workflow::Running;
pub use crate::xes::XesLog;

Modules§

admission: Admission and refusal: the first-class boundary verdict surface. Admission and refusal — the first-class boundary verdict surface.
bpmn: BPMN model shape. BPMN model shape — structure only, no execution semantics.
causal_net: Causal net structural shapes (Heuristics Miner output — Weijters & Ribeiro 2011). Causal net structural shapes — Weijters & Ribeiro (2011) Heuristics Miner output.
causality: Causal consistency law: CausalChain, CausalLink, CausalConsistency, CausallyOrderedEvidence.
conformance: Conformance verdict shape (structure only — no checking engine). Conformance verdict shape — structure only, does NOT compute conformance.
correlation: Cross-log correlation law: CorrelationKey, CorrelatedLog, CorrelationSchema shapes.
declare: Declare constraint shape. Declare and OC-Declare constraint shapes — structure only.
dfg: Directly-follows graph (DFG) shape. Directly-Follows Graph (DFG) shape — the graph, not the discovery algorithm.
diagnostic: Diagnostic shapes for explaining admission and refusal. Compatibility diagnostics — the named laws of a well-formed compat surface.
eventlog: Event, trace, and event-log shapes. Case-centric event-log grammar — the classical process-mining shape.
evidence: Receipt-shaped evidence values (structure only). Evidence — a value carried together with its lifecycle stage and witness.
formats: Import/export contracts, round-trip claims, and loss surfaces. Format import/export contracts, round-trip claims, and loss surfaces.
ids: Zero-cost #[repr(transparent)] identifier wrappers. Zero-cost, kind-typed identifier wrappers.
interop: Interop traits: import, export, round-trip claim plumbing. Always-on adoption grammar for interoperating with external process-mining ecosystems (PM4Py, PMAx, and friends) — without cloning their internals.
law: Compile-time law kernel: ConstParamTy enums, bounds machinery, ConditionCell, Between01. Compile-time law kernel — ConstParamTy enums, bounds machinery, and type-level invariants derived from process-mining papers and the Blue River Dam covenant.
loss: Loss policy, loss report, and named projection law. Loss policy, loss report, named-projection law, and named-loss descriptor.
multiperspective: Multi-perspective process evidence: ControlFlow/Data/Resource/Time perspective markers.
nightly_foundry: Nightly foundry: zero-cost type-law surfaces from process-mining papers.
object_lifecycle: Object lifecycle law: typed phase markers and lawful phase transitions.
ocel: Object-centric event log (OCEL) shape. Object-Centric Event Log (OCEL) shape — first-class, not “event log plus extras”.
ocpq: Object-centric process query (OCPQ) shape. OCPQ (Object-Centric Process Query) shapes — query structure only, no execution.
petri: Petri net shape. Petri net, WF-net, and OC-Petri-net shapes — with soundness as a typestate claim, never a computed proof.
powl: POWL (partially ordered workflow language) shape. POWL (Partially Ordered Workflow Language) shape — first-class, structure only.
powl8_op: POWL8 operator discriminant — compact u8 wire-format companion to crate::powl::PowlNodeKind. POWL8 operator discriminant — compact wire-format companion to crate::powl::PowlNodeKind.
prediction: Prediction problem shape (structure only — no predictor). Prediction problem shape — structure only, does NOT predict.
prelude: Core adoption surface — re-exports the most-needed shapes and laws. The adoption prelude — the smallest surface needed to start using the crate.
process_cube: Process cube dimensional structure (van der Aalst 2013 — multi-perspective comparison).
process_tree: Process tree shape. Process tree shape — structure only.
receipt: Receipt shape: provenance-bearing evidence envelope. Receipt-shaped evidence — structure only, carries no full authority.
state: Typestate tokens: Raw, Parsed, Admitted, Refused, Projected, … Typestate tokens — the evidence lifecycle, tracked at the type level.
streaming: Streaming evidence context law: online vs. offline collection markers and EventWindow.
temporal: Temporal ordering and profile law surfaces.
witness: Witness markers and witness families (type-level proof carriers). Witness markers — type-level proof carriers naming the canon a value answers to.
witnesses: Compiled witness marker declarations — one entry per WitnessMarker in the ontology. Generated by ggen sync --rule witness-markers; maintained via TTL + ggen, not by hand. Witness marker declarations — compiled from wasm4pm-compat.ttl.
workflow: Typestate-based parallel workflow tracking. Parallel Workflow Typestate Model.
xes: XES interchange shape. XES interchange grammar — the IEEE 1849 event-log/stream exchange shape.