wasm4pm-compat 26.6.5

//! Always-on **adoption grammar** for interoperating with external process-mining
//! ecosystems (PM4Py, PMAx, and friends) — *without* cloning their internals.
//!
//! This module is the smallest, always-available vocabulary a host tool needs to
//! describe what it is *handing across the boundary* and what it is *claiming*
//! about that handoff. It is **structure only**: it carries no PM4Py objects, runs
//! no discovery, no conformance checking, no replay, and no statistics. It merely
//! lets an adopter *name* the shapes it intends to admit, and *refuse* — with a
//! specific named law — when a claim is not grounded.
//!
//! ## What this module **IS**
//!
//! - A set of small, transparent *shape descriptors* ([`crate::interop::Pm4pyShape`],
//!   [`crate::interop::FilterShape`], [`crate::interop::SummaryShape`], [`crate::interop::ConformanceTriple`]) that describe the
//!   *kind* of artifact being adopted, never its bytes or its computed values.
//! - An [`crate::interop::ArtifactGrounding`] that ties a claimed artifact to the evidence that
//!   justifies admitting it.
//! - A first-class refusal enum, [`crate::interop::InteropRefusal`], for when a claim cannot be
//!   grounded.
//!
//! ## What this module is **NOT**
//!
//! - **Not** a PM4Py / PMAx re-implementation. There are no DataFrames, no
//!   PetriNet objects, no alignment matrices here.
//! - **Not** an engine. Nothing here *computes* a summary, a filter result, or a
//!   conformance triple — it only describes their *shape* so the boundary can
//!   reason about admission and refusal.
//!
//! ## Graduation
//!
//! These descriptors should graduate to `wasm4pm` the moment a host needs the
//! values behind them *computed or executed* (an actual filter applied, an actual
//! summary tallied, an actual conformance triple measured). At that point the
//! shape becomes a job, and a job belongs to the engine — see the `wasm4pm`
//! feature and the `graduation` module.

use core::marker::PhantomData;

/// The *kind* of PM4Py-flavoured artifact an adopter is presenting at the boundary.
///
/// This describes **what category of thing** is crossing the boundary so the
/// compat layer can pick the right admission law. It does **not** hold the
/// artifact itself, and it is **structure only** — naming a `PetriNet` here does
/// not bring a Petri-net engine with it.
///
/// Graduate to `wasm4pm` when you need the artifact *materialized and executed*
/// rather than merely *named and admitted*.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Pm4pyShape {
    /// A flat (single-case-notion) event log, à la PM4Py `EventLog`.
    EventLog,
    /// An object-centric event log, à la PM4Py OCEL.
    ObjectCentricLog,
    /// A Petri net model surface (places/transitions), structure only.
    PetriNet,
    /// A process tree model surface, structure only.
    ProcessTree,
    /// A BPMN model surface, structure only.
    Bpmn,
    /// A directly-follows graph, structure only.
    DirectlyFollowsGraph,
    /// A declarative (Declare) constraint surface, structure only.
    Declare,
}

impl Pm4pyShape {
    /// A short, stable, machine-readable tag for this shape.
    ///
    /// ```
    /// use wasm4pm_compat::interop::Pm4pyShape;
    /// assert_eq!(Pm4pyShape::EventLog.tag(), "event_log");
    /// assert_eq!(Pm4pyShape::ObjectCentricLog.tag(), "ocel");
    /// ```
    #[must_use]
    pub const fn tag(self) -> &'static str {
        match self {
            Pm4pyShape::EventLog => "event_log",
            Pm4pyShape::ObjectCentricLog => "ocel",
            Pm4pyShape::PetriNet => "petri_net",
            Pm4pyShape::ProcessTree => "process_tree",
            Pm4pyShape::Bpmn => "bpmn",
            Pm4pyShape::DirectlyFollowsGraph => "dfg",
            Pm4pyShape::Declare => "declare",
        }
    }

    /// Whether this shape is object-centric (multiple object notions) rather than
    /// flat (a single case notion).
    ///
    /// ```
    /// use wasm4pm_compat::interop::Pm4pyShape;
    /// assert!(Pm4pyShape::ObjectCentricLog.is_object_centric());
    /// assert!(!Pm4pyShape::EventLog.is_object_centric());
    /// ```
    #[must_use]
    pub const fn is_object_centric(self) -> bool {
        matches!(self, Pm4pyShape::ObjectCentricLog)
    }
}

/// The *shape* of a log filter an adopter intends to declare at the boundary.
///
/// This names the **dimension** a filter ranges over (activity, time, variant, …)
/// — it carries **no predicate, no threshold, and no filtered result**. It exists
/// so the compat layer can record *that a filter was claimed* without pretending
/// to *apply* one.
///
/// Graduate to `wasm4pm` when the filter must actually *select* events/traces.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum FilterShape {
    /// Filter by activity / event name.
    Activity,
    /// Filter by timestamp window.
    Timeframe,
    /// Filter by trace variant.
    Variant,
    /// Filter by attribute presence or value class (no value held here).
    Attribute,
    /// Filter by object type (object-centric).
    ObjectType,
}

/// The *shape* of a log summary an adopter intends to declare.
///
/// Names the **family of statistic** being summarized (counts, variants,
/// durations, …). It holds **no tallies**: a `SummaryShape::TraceVariants` does
/// not contain the variants, only the assertion that variant-summary is the
/// claimed shape.
///
/// Graduate to `wasm4pm` when the summary must actually be *tallied*.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum SummaryShape {
    /// Counts of events / traces / objects.
    Counts,
    /// The set of distinct trace variants.
    TraceVariants,
    /// Activity / event-name distribution.
    ActivityDistribution,
    /// Throughput / cycle-time profile.
    TimingProfile,
    /// Object-type distribution (object-centric).
    ObjectTypeDistribution,
}

/// A *shape* describing the three classic conformance quality dimensions, with
/// **no values measured**.
///
/// In full process mining a conformance result reports fitness, precision, and
/// (optionally) generalization. Here we only assert *which dimensions are being
/// claimed* — the booleans say "this dimension is part of the claim", they do
/// **not** carry the measured score. Measuring belongs to the engine.
///
/// Graduate to `wasm4pm` when the actual fitness/precision/generalization numbers
/// must be *computed by replay or alignment*.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ConformanceTriple {
    /// The claim includes a fitness dimension.
    pub claims_fitness: bool,
    /// The claim includes a precision dimension.
    pub claims_precision: bool,
    /// The claim includes a generalization dimension.
    pub claims_generalization: bool,
}

impl ConformanceTriple {
    /// A triple that claims fitness and precision but not generalization — the
    /// most common conformance shape.
    ///
    /// ```
    /// use wasm4pm_compat::interop::ConformanceTriple;
    /// let t = ConformanceTriple::fitness_and_precision();
    /// assert!(t.claims_fitness && t.claims_precision);
    /// assert!(!t.claims_generalization);
    /// ```
    #[must_use]
    pub const fn fitness_and_precision() -> Self {
        Self {
            claims_fitness: true,
            claims_precision: true,
            claims_generalization: false,
        }
    }

    /// How many of the three dimensions this triple claims.
    ///
    /// ```
    /// use wasm4pm_compat::interop::ConformanceTriple;
    /// assert_eq!(ConformanceTriple::fitness_and_precision().claimed_count(), 2);
    /// ```
    #[must_use]
    pub const fn claimed_count(self) -> u8 {
        (self.claims_fitness as u8)
            + (self.claims_precision as u8)
            + (self.claims_generalization as u8)
    }

    /// Whether the triple claims at least one dimension. An empty triple is a
    /// vacuous conformance claim and should be refused at admission.
    ///
    /// ```
    /// use wasm4pm_compat::interop::ConformanceTriple;
    /// let empty = ConformanceTriple { claims_fitness: false, claims_precision: false, claims_generalization: false };
    /// assert!(!empty.is_grounded());
    /// ```
    #[must_use]
    pub const fn is_grounded(self) -> bool {
        self.claimed_count() > 0
    }
}

/// Ties a claimed PM4Py-flavoured artifact to the *evidence handle* that justifies
/// admitting it across the boundary.
///
/// `ArtifactGrounding` is the unit of honesty in the interop grammar: an adopter
/// may not merely *assert* "I have a Petri net"; it must point at the evidence
/// (named by `evidence_ref`) that grounds the assertion. The generic `W` is a
/// witness family marker (see [`crate::witness`]) carried at the type level only —
/// `PhantomData`, zero runtime cost.
///
/// It is **structure only**: it never holds the artifact, and grounding it does
/// not validate it. Validation/execution is a `wasm4pm` job.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ArtifactGrounding<W> {
    /// The kind of artifact being grounded.
    pub shape: Pm4pyShape,
    /// An opaque reference to the evidence that grounds this artifact (e.g. a
    /// content hash, fixture name, or receipt id). Structure-only: the compat
    /// layer does not dereference it.
    pub evidence_ref: String,
    /// Type-level witness family marker. Zero-cost.
    pub witness: PhantomData<W>,
}

impl<W> ArtifactGrounding<W> {
    /// Ground an artifact `shape` against an opaque `evidence_ref`.
    ///
    /// ```
    /// use wasm4pm_compat::interop::{ArtifactGrounding, Pm4pyShape};
    /// let g = ArtifactGrounding::<()>::new(Pm4pyShape::EventLog, "blake3:abc");
    /// assert_eq!(g.shape, Pm4pyShape::EventLog);
    /// assert!(g.is_grounded());
    /// ```
    #[must_use]
    pub fn new(shape: Pm4pyShape, evidence_ref: impl Into<String>) -> Self {
        Self {
            shape,
            evidence_ref: evidence_ref.into(),
            witness: PhantomData,
        }
    }

    /// Whether the grounding actually references evidence. An empty
    /// `evidence_ref` is an ungrounded claim and must be refused with
    /// [`InteropRefusal::UngroundedArtifact`].
    ///
    /// ```
    /// use wasm4pm_compat::interop::{ArtifactGrounding, Pm4pyShape};
    /// let bad = ArtifactGrounding::<()>::new(Pm4pyShape::PetriNet, "");
    /// assert!(!bad.is_grounded());
    /// ```
    #[must_use]
    pub fn is_grounded(&self) -> bool {
        !self.evidence_ref.trim().is_empty()
    }

    /// Admit this grounding, or refuse with a *specific named law*.
    ///
    /// This is the always-on, structure-only admission gate of the interop
    /// grammar. It does **not** validate the artifact's contents (that is an
    /// engine job); it only enforces that the claim is *grounded* and that an
    /// object-centric shape was not smuggled in under a flat claim.
    ///
    /// ```
    /// use wasm4pm_compat::interop::{ArtifactGrounding, Pm4pyShape, InteropRefusal};
    /// let g = ArtifactGrounding::<()>::new(Pm4pyShape::ObjectCentricLog, "ocel:fixture-1");
    /// assert!(g.admit_flat().is_err()); // OCEL refused under a flat claim
    /// assert!(matches!(g.admit_flat(), Err(InteropRefusal::FlatClaimOverObjectCentric)));
    /// ```
    #[must_use = "check the shape-check result"]
    pub fn admit_flat(&self) -> Result<(), InteropRefusal> {
        if !self.is_grounded() {
            return Err(InteropRefusal::UngroundedArtifact);
        }
        if self.shape.is_object_centric() {
            return Err(InteropRefusal::FlatClaimOverObjectCentric);
        }
        Ok(())
    }
}

/// First-class, *specifically named* refusals for the interop grammar.
///
/// Refusal is never bare here. Each variant names the exact law violated so a
/// host (and a human) can see *why* the boundary said no. These are
/// **structure-only** verdicts: they describe a boundary judgment, they do not
/// remediate it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum InteropRefusal {
    /// A claimed artifact carried no evidence reference to ground it.
    UngroundedArtifact,
    /// A flat admission path was used for an object-centric artifact, which would
    /// silently collapse object notions. Use the object-centric path instead.
    FlatClaimOverObjectCentric,
    /// A conformance claim named *zero* of fitness/precision/generalization and is
    /// therefore vacuous.
    VacuousConformanceClaim,
    /// A summary or filter shape was declared for a dimension the named artifact
    /// shape cannot possibly carry (e.g. `FilterShape::ObjectType` over a flat
    /// `Pm4pyShape::EventLog`).
    DimensionShapeMismatch,
    /// The adopter tried to interpret raw external bytes as a typed artifact
    /// without first admitting them — raw-to-typed laundering is refused.
    UnadmittedRawInterpretation,
}

impl InteropRefusal {
    /// The stable law-name string for this refusal, suitable for diagnostics and
    /// receipts.
    ///
    /// ```
    /// use wasm4pm_compat::interop::InteropRefusal;
    /// assert_eq!(InteropRefusal::UngroundedArtifact.law(), "UngroundedArtifact");
    /// ```
    #[must_use]
    pub const fn law(self) -> &'static str {
        match self {
            InteropRefusal::UngroundedArtifact => "UngroundedArtifact",
            InteropRefusal::FlatClaimOverObjectCentric => "FlatClaimOverObjectCentric",
            InteropRefusal::VacuousConformanceClaim => "VacuousConformanceClaim",
            InteropRefusal::DimensionShapeMismatch => "DimensionShapeMismatch",
            InteropRefusal::UnadmittedRawInterpretation => "UnadmittedRawInterpretation",
        }
    }
}

impl core::fmt::Display for InteropRefusal {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "interop refusal: {}", self.law())
    }
}

/// Check that a [`FilterShape`] is meaningful for a given [`Pm4pyShape`].
///
/// Object-centric filter dimensions (`ObjectType`) are refused over flat shapes;
/// everything else is structurally admissible. This is a *shape* check only — it
/// does not validate that any matching events exist.
///
/// ```
/// use wasm4pm_compat::interop::{check_filter_shape, FilterShape, Pm4pyShape, InteropRefusal};
/// assert!(check_filter_shape(Pm4pyShape::EventLog, FilterShape::Activity).is_ok());
/// assert_eq!(
///     check_filter_shape(Pm4pyShape::EventLog, FilterShape::ObjectType),
///     Err(InteropRefusal::DimensionShapeMismatch)
/// );
/// ```
#[must_use = "check the shape-check result"]
pub fn check_filter_shape(artifact: Pm4pyShape, filter: FilterShape) -> Result<(), InteropRefusal> {
    if matches!(filter, FilterShape::ObjectType) && !artifact.is_object_centric() {
        return Err(InteropRefusal::DimensionShapeMismatch);
    }
    Ok(())
}

// ── OCEL → XES format grammar surfaces ──────────────────────────────────────
//
// The following types model the *named projection descriptor* for OCEL→XES
// flattening. They are the format grammar surfaces of the boundary — they name
// and parameterise the projection but do NOT implement it. The projection
// itself (instantiating crate::loss::Project) belongs in the adopter's code or
// in `wasm4pm`.

/// A descriptor for an OCEL→XES flattening projection.
///
/// Flattening OCEL to a single XES case notion is lossy: you choose one object
/// type to act as the case, and all E2O links to the other types are dropped.
/// This descriptor names the projection (via [`crate::loss::ProjectionName`])
/// and records which object type was chosen as the case notion.
///
/// It is the *grammar surface* for the OCEL→XES boundary: it names and
/// parameterises the projection so the [`crate::loss::Project`] impl an adopter
/// writes is unambiguous and auditable. It does **not** perform the flattening.
///
/// Structure-only: use this as the `Self` type of a
/// [`crate::loss::Project`] impl, with `From = OcelShape`, `To = XesShape`,
/// `Lost = Vec<String>` (dropped object type names), and
/// `Reason = crate::ocel::OcelRefusal`.
///
/// ```
/// use wasm4pm_compat::interop::OcelToXesProjection;
/// use wasm4pm_compat::loss::ProjectionName;
/// let proj = OcelToXesProjection::new("order");
/// assert_eq!(proj.case_type(), "order");
/// assert_eq!(proj.projection_name().as_str(), "ocel-flatten-to-xes:by-case-type");
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct OcelToXesProjection {
    case_type: String,
}

impl OcelToXesProjection {
    /// The stable [`crate::loss::ProjectionName`] for this family of projections.
    pub const PROJECTION_NAME: crate::loss::ProjectionName =
        crate::loss::ProjectionName("ocel-flatten-to-xes:by-case-type");

    /// Construct a projection descriptor for flattening OCEL by `case_type`.
    ///
    /// ```
    /// use wasm4pm_compat::interop::OcelToXesProjection;
    /// let p = OcelToXesProjection::new("order");
    /// assert_eq!(p.case_type(), "order");
    /// ```
    pub fn new(case_type: impl Into<String>) -> Self {
        OcelToXesProjection {
            case_type: case_type.into(),
        }
    }

    /// The object type chosen as the XES case notion.
    ///
    /// ```
    /// use wasm4pm_compat::interop::OcelToXesProjection;
    /// assert_eq!(OcelToXesProjection::new("item").case_type(), "item");
    /// ```
    pub fn case_type(&self) -> &str {
        &self.case_type
    }

    /// The stable [`crate::loss::ProjectionName`] for this projection family.
    ///
    /// ```
    /// use wasm4pm_compat::interop::OcelToXesProjection;
    /// let p = OcelToXesProjection::new("order");
    /// assert_eq!(p.projection_name().as_str(), "ocel-flatten-to-xes:by-case-type");
    /// ```
    pub fn projection_name(&self) -> crate::loss::ProjectionName {
        Self::PROJECTION_NAME
    }
}

/// Shape marker for the OCEL side of an OCEL→XES projection.
///
/// Use as `From` in `LossReport<OcelShape, XesShape, …>` and in
/// [`crate::loss::Project`] impls. Zero-sized.
///
/// ```
/// use wasm4pm_compat::interop::OcelShape;
/// let _: OcelShape;
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum OcelShape {}

/// Shape marker for the XES side of an OCEL→XES projection.
///
/// Use as `To` in `LossReport<OcelShape, XesShape, …>` and in
/// [`crate::loss::Project`] impls. Zero-sized.
///
/// ```
/// use wasm4pm_compat::interop::XesShape;
/// let _: XesShape;
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum XesShape {}

// ── XES → OCED format grammar surfaces ──────────────────────────────────────
//
// The OCED meta-model (Object-Centric Event Data) is a richer formalism than
// XES: where XES is case-centric and single-case-notion, OCED is object-centric
// and multi-entity. Converting XES to OCED is therefore a *named, lossy
// projection*: the XES single-case assumption is dropped, object relationships
// are inferred, and the resulting OCED log explicitly accounts for what was
// structurally implicit in XES.
//
// Law: xes-to-oced-projection-named
// Paper: "Object-Centric Analysis of XES Event Logs: Integrating OCED Modeling
//         with SPARQL Queries"
//
// The reverse direction (OCEL→XES) is covered by OcelToXesProjection above.

/// Shape marker for the OCED (Object-Centric Event Data) side of a XES→OCED
/// projection.
///
/// Use as `To` in `LossReport<XesShape, OcedShape, …>` and in
/// [`crate::loss::Project`] impls for XES-to-OCED projections. Zero-sized.
///
/// This is **not** the same as [`OcelShape`]: OCED is the upstream meta-model
/// formalism (IEEE/WfMC academic standard), while OCEL is the concrete 2.0
/// serialization. They are distinct projection targets.
///
/// ## Graduation
///
/// OCED evaluation, SPARQL queries over OCED graphs, and OCED-to-OCEL
/// materialization graduate to `wasm4pm`. This marker is structure-only.
///
/// ```
/// use wasm4pm_compat::interop::OcedShape;
/// let _: OcedShape;
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum OcedShape {}

/// A descriptor for a XES→OCED lifting projection.
///
/// Converting XES (case-centric, single case notion, no explicit object types)
/// into the OCED meta-model is *lossy*: the XES single-case assumption is
/// dropped, object relationships are inferred from the trace structure, and the
/// single-case-notion constraint is lost. This descriptor names that projection
/// (via [`crate::loss::ProjectionName`]) and records the object type introduced
/// as the case notion in the OCED output.
///
/// It is the *grammar surface* for the XES→OCED boundary: it names and
/// parameterises the projection so the [`crate::loss::Project`] impl an adopter
/// writes is unambiguous and auditable. It does **not** perform the lifting.
///
/// Structure-only: use this as the `Self` type of a
/// [`crate::loss::Project`] impl, with `From = XesShape`, `To = OcedShape`,
/// `Lost = Vec<String>` (structural assumptions dropped), and
/// `Reason = crate::xes::XesRefusal`.
///
/// ## Law
///
/// `xes-to-oced-projection-named` — Paper: "Object-Centric Analysis of XES
/// Event Logs: Integrating OCED Modeling with SPARQL Queries"
///
/// ```
/// use wasm4pm_compat::interop::XesToOcedProjection;
/// use wasm4pm_compat::loss::ProjectionName;
/// let proj = XesToOcedProjection::new("order");
/// assert_eq!(proj.introduced_object_type(), "order");
/// assert_eq!(proj.projection_name().as_str(), "xes-lift-to-oced:by-case-type");
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct XesToOcedProjection {
    introduced_object_type: String,
}

impl XesToOcedProjection {
    /// The stable [`crate::loss::ProjectionName`] for this family of projections.
    pub const PROJECTION_NAME: crate::loss::ProjectionName =
        crate::loss::ProjectionName("xes-lift-to-oced:by-case-type");

    /// Construct a projection descriptor for lifting XES by introducing
    /// `object_type` as the primary case-notion object type in OCED.
    ///
    /// ```
    /// use wasm4pm_compat::interop::XesToOcedProjection;
    /// let p = XesToOcedProjection::new("order");
    /// assert_eq!(p.introduced_object_type(), "order");
    /// ```
    pub fn new(object_type: impl Into<String>) -> Self {
        XesToOcedProjection {
            introduced_object_type: object_type.into(),
        }
    }

    /// The object type introduced as the case notion in the OCED output.
    ///
    /// ```
    /// use wasm4pm_compat::interop::XesToOcedProjection;
    /// assert_eq!(XesToOcedProjection::new("item").introduced_object_type(), "item");
    /// ```
    pub fn introduced_object_type(&self) -> &str {
        &self.introduced_object_type
    }

    /// The stable [`crate::loss::ProjectionName`] for this projection family.
    ///
    /// ```
    /// use wasm4pm_compat::interop::XesToOcedProjection;
    /// let p = XesToOcedProjection::new("order");
    /// assert_eq!(p.projection_name().as_str(), "xes-lift-to-oced:by-case-type");
    /// ```
    pub fn projection_name(&self) -> crate::loss::ProjectionName {
        Self::PROJECTION_NAME
    }
}

// ── Graduation candidate sealed marker ──────────────────────────────────────
//
// Always-on (base profile): the graduation boundary is part of the core
// interop grammar, not an optional feature. Structure-only in wasm4pm-compat;
// execution graduates to wasm4pm.

/// Sealed marker: a type that is a **graduation candidate** — it requires the
/// `wasm4pm` execution engine to resolve its structural claim and therefore
/// must not grow engine logic inside `wasm4pm-compat`.
///
/// This trait is *sealed* (`graduation_seal::Sealed`): only types that
/// explicitly opt in via `impl graduation_seal::Sealed for MyType {}` can
/// implement it. The seal prevents third-party crates from accidentally
/// marking arbitrary types as graduation candidates without declaring the
/// boundary seam.
///
/// ## What this trait is **NOT**
///
/// - **Not** the act of graduation. Implementing `GraduationCandidate` does
///   not graduate anything; it makes the boundary explicit at the type level.
/// - **Not** an engine. No execution, no discovery, no replay, no conformance
///   checking. Structure only.
///
/// ## Graduation
///
/// When a host needs a graduation candidate value (reason + subject +
/// evidence ref), use `wasm4pm_compat::graduation::GraduateToWasm4pm`
/// (behind the `wasm4pm` feature). This sealed marker is the always-on
/// compile-time surface that `GraduateToWasm4pm` implementors should also
/// implement at the seam.
///
/// ## Usage pattern
///
/// ```
/// use wasm4pm_compat::interop::{GraduationCandidate, graduation_seal};
///
/// struct PendingOcelDiscovery;
///
/// impl graduation_seal::Sealed for PendingOcelDiscovery {}
/// impl GraduationCandidate for PendingOcelDiscovery {}
///
/// fn only_graduation_candidates<T: GraduationCandidate>(_: &T) {}
/// only_graduation_candidates(&PendingOcelDiscovery);
/// ```
pub trait GraduationCandidate: graduation_seal::Sealed {}

/// Sealing module for [`GraduationCandidate`].
///
/// To implement [`GraduationCandidate`], a type must first implement
/// `graduation_seal::Sealed`. This is the sealed-trait pattern in stable Rust.
pub mod graduation_seal {
    /// The seal. Implement this for your type before implementing
    /// [`super::GraduationCandidate`].
    pub trait Sealed {}
}

// ── Compile-time filter-shape law ────────────────────────────────────────────
//
// `FilterShapeConst<IS_OC>` is the type-level surface for the pm4py shape law:
// an object-centric filter dimension (ObjectType) must only be applied to an
// object-centric artifact shape.  The boolean const parameter names whether the
// artifact is object-centric.  `assert_filter_oc_compatible` requires the
// sealed `RequiresObjectCentric` bound, which only `FilterShapeConst<true>`
// satisfies — so passing `FilterShapeConst<false>` (a flat artifact) is a
// compile error named `DimensionShapeMismatch`.
//
// Law: DimensionShapeMismatch — FilterShape::ObjectType over a flat Pm4pyShape.

/// A compile-time artifact-centricity tag for the filter-shape law.
///
/// `IS_OC` encodes whether the artifact is object-centric (`true`) or flat
/// (`false`). Pass `FilterShapeConst::<true>` to surfaces that require an
/// object-centric shape; `FilterShapeConst::<false>` fails those surfaces at
/// compile time with the `DimensionShapeMismatch` law.
///
/// This is **structure only** and **zero-cost**: no runtime value is stored.
///
/// ```
/// use wasm4pm_compat::interop::{FilterShapeConst, assert_filter_oc_compatible};
/// assert_filter_oc_compatible(&FilterShapeConst::<true>);  // object-centric: lawful
/// ```
///
/// ```compile_fail
/// use wasm4pm_compat::interop::{FilterShapeConst, assert_filter_oc_compatible};
/// // flat artifact: DimensionShapeMismatch law — FilterShape::ObjectType is refused
/// assert_filter_oc_compatible(&FilterShapeConst::<false>);
/// ```
pub struct FilterShapeConst<const IS_OC: bool>;

mod filter_shape_seal {
    pub trait Sealed {}
    impl Sealed for super::FilterShapeConst<true> {}
    // FilterShapeConst<false> is deliberately NOT sealed:
    // applying an ObjectType filter to a flat shape violates DimensionShapeMismatch.
}

/// Sealed marker: only `FilterShapeConst<true>` (object-centric) satisfies this
/// bound. Attempting to apply an object-centric filter (`FilterShape::ObjectType`)
/// to a flat artifact shape (`FilterShapeConst<false>`) is a compile error
/// enforcing the `DimensionShapeMismatch` law.
pub trait RequiresObjectCentric: filter_shape_seal::Sealed {}
impl RequiresObjectCentric for FilterShapeConst<true> {}

/// Type-law gate: only object-centric artifact shapes compile through this
/// function when an `ObjectType` filter is declared.
///
/// Passing `FilterShapeConst::<false>` (a flat shape) is a compile error that
/// enforces the `DimensionShapeMismatch` pm4py shape law at the type level.
///
/// ```
/// use wasm4pm_compat::interop::{FilterShapeConst, assert_filter_oc_compatible};
/// assert_filter_oc_compatible(&FilterShapeConst::<true>);
/// ```
pub fn assert_filter_oc_compatible<F: RequiresObjectCentric>(_: &F) {}

impl crate::loss::Project for OcelToXesProjection {
    type From = OcelShape;
    type To = XesShape;
    type Lost = Vec<String>;
    type Reason = crate::ocel::OcelRefusal;

    fn project(
        self,
        policy: crate::loss::LossPolicy,
    ) -> Result<crate::loss::LossReport<Self::From, Self::To, Self::Lost>, Self::Reason> {
        if policy == crate::loss::LossPolicy::RefuseLoss {
            return Err(crate::ocel::OcelRefusal::FlatteningLoss);
        }
        Ok(crate::loss::LossReport::new(
            self.projection_name(),
            policy,
            Vec::new(),
        ))
    }
}

impl crate::loss::Project for XesToOcedProjection {
    type From = XesShape;
    type To = OcedShape;
    type Lost = Vec<String>;
    type Reason = crate::xes::XesRefusal;

    fn project(
        self,
        policy: crate::loss::LossPolicy,
    ) -> Result<crate::loss::LossReport<Self::From, Self::To, Self::Lost>, Self::Reason> {
        if policy == crate::loss::LossPolicy::RefuseLoss {
            return Err(crate::xes::XesRefusal::LiftingLoss);
        }
        Ok(crate::loss::LossReport::new(
            self.projection_name(),
            policy,
            Vec::new(),
        ))
    }
}