ex4pm

# ex4pm

ex4pm is a BEAM-native, evidence-oriented process-intelligence system derived from the semantic laws of wasm4pm rather than from its directory structure.

It keeps process semantics portable while using OTP for supervision, streaming, distributed execution, planning, and continuously operating process intelligence.

## Governing calculus

```text
observation
  -> parse
  -> route
  -> admit | refuse
  -> construct
  -> BRCE
  -> DO
  -> receipt
  -> replay
  -> bounded standing
```

`SELECT`, `CONSTRUCT`, and `DO` are intentionally separate. Hooks and planners can manufacture intents and candidate plans, but only the BRCE broker may execute a state-changing callback.

## DfCM engine graph

The engine registry preserves these candidates simultaneously:

- `:beam` - native deterministic Elixir algorithms;
- `:ex4pm_plan` - pinned ex4pm-plan cloud planning worker protocol;
- `:wasm` - Wasmex/Wasmtime execution of admitted WebAssembly artifacts;
- `:nif` - configured native NIF module;
- `:remote` - configured remote engine callback.

Selection is capability- and evidence-driven. An unavailable edge yields a typed standing/refusal instead of silently disappearing.

## Installation

```elixir
def deps do
  [{:ex4pm, "~> 26.9.30"}]
end
```

## Library layout

ex4pm is a single flat, hex-publishable Mix library (app `:ex4pm`) — no separate OTP apps.
`lib/ex4pm/` is organized into namespaced module directories:

- `lib/ex4pm/aloop.ex` - independent online process intelligence over ALOOP OCEL event logs (episodes, loop depth/recurrence, causal edges, DFG/variants/precision, conformance, analysis receipts);
- `lib/ex4pm/contracts.ex` - canonical ontology, SHACL, WIT component contract, and receipt schema;
- `lib/ex4pm/core/` - canonical observation IR, OCEL/XES normalization, POWL, capabilities, hashing;
- `lib/ex4pm/evidence/` - receipts, replay, receipt store, BRCE;
- `lib/ex4pm/engine/` - engine calculus, BEAM discovery/conformance/simulation, ex4pm-plan, WASM/NIF/remote adapters, differential verification;
- `lib/ex4pm/runtime/` - POWL planning and receipted OTP execution;
- `lib/ex4pm/stream/` - Broadway ingestion with backpressure and acknowledgement;
- `lib/ex4pm/domain/` - Ash/ETS semantic-control-plane projection;
- `lib/ex4pm.ex` - public orchestration API;
- `lib/ex4pm/cli.ex` - command-line projection.

The Phoenix/LiveView demo web app lives outside the published library, under
`test/demo_web/`, compiled only in the `:test` environment.

## Public API

```elixir
{:ok, dataset} = Ex4pm.ingest(ocel_map)
{:ok, dataset} = Ex4pm.ingest_xes(xes_xml)
{:ok, run} = Ex4pm.discover(dataset, algorithm: :dfg, object_type: "Order")
{:ok, report} = Ex4pm.conform(dataset, run.value)
{:ok, paths} = Ex4pm.simulate(run.value, max_depth: 12, max_paths: 128)
{:ok, candidates} = Ex4pm.optimize(dataset, run.value)
{:ok, plan} = Ex4pm.plan(problem, ex4pm_plan_fun: planner_transport)
{:ok, replayed} = Ex4pm.replay(run.receipt.hash)
{:ok, contract} = Ex4pm.contracts()
```

`plan/2` is an analytical CONSTRUCT path. Its planner transport is explicit, its result is receipted, and an exact ex4pm-plan capsule reaches `ALIVE` only when the transport reports the pinned source identity plus an image digest and the worker reports replay verification. The planner adapter never receives ambient cloud credentials.

`operate/3` is different: it requires an explicit authority map and all task callbacks cross the BRCE boundary. A plan returned by `plan/2` has no ambient DO authority.

## ex4pm-plan bridge

The maintained planning worker is [seanchatmangpt/ex4pm-plan](https://github.com/seanchatmangpt/ex4pm-plan), an 80/20 downstream distribution of Airbus scikit-decide. The ex4pm adapter is pinned to exact worker source `99816fb389670174be44ddaaf3b42f00496e6f21` and protocol `ex4pm-plan/v1`.

The injected `ex4pm_plan_fun` is the cloud-placement boundary. It may launch an OCI worker through Kubernetes, AWS, Azure, GCP, Fly.io, or another scheduler, but provider credentials and launch authority remain outside the planner adapter. The callback returns the worker response and, when available, an observed capsule identity:

```elixir
fn request, opts ->
  {:ok, response,
   %{
     observed: true,
     source_sha: Ex4pm.Engine.Ex4pmPlan.source_sha(),
     image_digest: "sha256:..."
   }}
end
```

A response without observed capsule identity remains `PARTIAL_ALIVE`; a mismatched observed source is refused.

## Canonical contracts

`Ex4pm.Contracts` (`lib/ex4pm/contracts.ex`) carries four executable identity surfaces:

- RDF/Turtle ontology for observations, models, engines, authority, actuation, and receipts;
- SHACL shapes for event/model/receipt closure;
- WIT component-world contract for portable process engines;
- JSON Schema for receipt interchange.

`Ex4pm.contracts/0` reads and hashes all four artifacts, verifies required semantic terms, and produces one contract hash. These are canonical public semantic surfaces; Ash records and engine-specific structs are projections.

## wasm4pm bridge

`Ex4pm.Engine.Wasm` is a real Wasmex-backed raw WebAssembly route. Because wasm4pm builds can expose build-specific ABIs, ex4pm does not invent an OCEL string ABI. The adapter only executes a configured export/parameter contract. A wasm4pm integration reaches `ALIVE` only when the exact artifact, export, parameters, output decoder, and replay evidence are all bound to one run.

The WIT component contract is a forward portable ex4pm engine boundary; it does not claim that arbitrary historical wasm4pm wasm-bindgen bundles already implement that component world.

### Building and supplying the wasm artifact

The Hex package does not bundle the wasm artifact. Build it from the wasm4pm repository
(`crates/wasm4pm-ex4pm-bindings/scripts/build-wasm.sh`, zero imports, 70 exports) and pass its
path as `artifact_path` to `Ex4pmEngine.Wasm.RealTransport.start/2`. The artifact is admitted
against the sha256 pin in `priv/wasm4pm/MANIFEST.json` (override with
`config :ex4pm, :wasm4pm_sha256`); a missing, mismatched or import-bearing artifact yields a typed
`%Ex4pm.Refusal{}`. `artifact.path` in the manifest is informational only and is never read.

## OCEL and XES

OCEL-v2-style object-centric data and XES case logs converge on the same canonical `Ex4pm.EventLog` IR. XES parsing disables DTD processing before XPath projection. A malformed activity/timestamp still reaches canonical admission and receives the same typed refusal as equivalent malformed OCEL.

## Ash control plane

Bulk event rows remain in the canonical event-log/artifact plane. Ash resources model datasets, process models, interventions, capabilities, and receipt projections. Projection is explicit via `Ex4pm.Domain.Projector` so persistence cannot silently change semantic truth.

## Streaming

`Ex4pm.Stream.Pipeline` accepts an event enumeration through Broadway, normalizes each event, provides backpressure, and invokes an explicit sink function. The sink receives observations; it does not gain ambient DO authority.

## Verification

```bash
mix deps.get
mix verify
```

The CI workflow runs formatting, warnings-as-errors compilation, the full test suite, and uploads `mix.lock` as a reproducibility artifact.

## Standing

Repository-wide standing begins at `PARTIAL_ALIVE`. Individual BEAM routes can become `ALIVE` after exact execution and replay. The ex4pm-plan route requires exact worker/capsule identity and replay evidence before `ALIVE`; optional WASM/NIF/remote routes remain `UNSUPPORTED`, `BLOCKED`, or `PARTIAL_ALIVE` until their exact runtime subjects execute.

See `docs/ARCHITECTURE.md` for the full graph and falsifiers.