BPMN-lite platform

Compilation-and-execution kernel for the V&S v1.1 vocabularies. A single Rust workspace (edition 2024, resolver "3", rust 1.95) ships two compiled vocabularies plus the vocabulary-neutral FFI catalogue that wires them together:

• bpmn-lite — process vocabulary: BPMN 2.0 XML → verified bytecode → fiber-based stack VM, exposed as a gRPC service on port 50051.
• dmn-lite — decision vocabulary: s-expression DSL → verified bytecode → stack VM, registered into the FFI catalogue via dmn-lite-bridge and invoked in-process from bpmn-lite via Instr::ExecFfi.

The dmn-lite repo was consolidated into this workspace during B0 (2026-05-16); both vocabularies now build, test, and version together as 18 peer crates. See CLAUDE.md for the unified crate map, architecture, A-phase status, and test counts.

Quick build

cargo build --workspace
cargo test  --workspace --exclude bpmn-lite-store-postgres

Runtime Contract

• Runtime invariants
• Executable BPMN subset

Boundary

• BPMN-lite owns its own database schema and migrations.
• BPMN-lite does not read or write "ob-poc".* database tables.
• The shared SessionStackState type is imported from ob-poc-types, but it is copied by value at the integration boundary.
• BPMN-lite persists its own copy on process_instances.session_stack and job_queue.session_stack.
• There is no shared database record and no live aliasing back into ob-poc session persistence.

Standalone Postgres Bootstrap

Create a dedicated database:

createdb bpmn_lite_test

Start the standalone server with Postgres enabled:

cd bpmn-lite
DATABASE_URL=postgresql:///bpmn_lite_test \
RUST_LOG=info \
cargo run -p bpmn-lite-server-runner --features postgres --bin bpmn-lite-server

On startup the server will:

1. connect to DATABASE_URL
2. apply BPMN-lite migrations from bpmn-lite-core/migrations
3. serve gRPC on 0.0.0.0:50051 by default

Override the bind address if needed:

cd bpmn-lite
DATABASE_URL=postgresql:///bpmn_lite_test \
BPMN_LITE_BIND=127.0.0.1:50061 \
cargo run -p bpmn-lite-server-runner --features postgres --bin bpmn-lite-server

Standalone Test Paths

Compile-only checks:

cd bpmn-lite
env RUSTC_WRAPPER= cargo check
env RUSTC_WRAPPER= cargo check -p bpmn-lite-server-runner --features postgres

Schema independence guard:

cd bpmn-lite
env RUSTC_WRAPPER= cargo test test_master_schema_is_standalone_from_ob_poc_namespace -- --nocapture

Copy-by-value session stack tests without Postgres:

cd bpmn-lite
env RUSTC_WRAPPER= cargo test test_start_with_session_stack_copies_value -- --nocapture
env RUSTC_WRAPPER= cargo test test_instance_session_stack_is_not_aliased -- --nocapture
env RUSTC_WRAPPER= cargo test test_job_queue_session_stack_is_not_aliased -- --nocapture

Postgres-backed standalone tests:

cd bpmn-lite
BPMN_LITE_TEST_DATABASE_URL=postgresql:///bpmn_lite_test \
env RUSTC_WRAPPER= cargo test -p bpmn-lite-core --features postgres test_pg_instance_round_trip -- --ignored --nocapture

BPMN_LITE_TEST_DATABASE_URL=postgresql:///bpmn_lite_test \
env RUSTC_WRAPPER= cargo test -p bpmn-lite-core --features postgres test_pg_instance_session_stack_copy_round_trip -- --ignored --nocapture

These Postgres tests use only BPMN-lite tables and mocked SessionStackState values. They do not require ob-poc migrations or ob-poc database tables.

Load Harness

Run the existing smoke profile against a standalone server:

cd bpmn-lite
cargo run -p xtask -- smoke --spawn-server --database-url postgresql:///bpmn_lite_test

Multi-Instance Docker Harness

xtask can now spin up isolated Docker deployments where each BPMN-lite server has its own Postgres container, network, and volume.

Bring up one instance:

cd bpmn-lite
cargo run -p xtask -- docker-up \
  --instance-name alpha \
  --server-port 50071 \
  --db-port 5541

Bring up a second independent instance:

cd bpmn-lite
cargo run -p xtask -- docker-up \
  --instance-name beta \
  --server-port 50072 \
  --db-port 5542

Each instance gets:

• its own BPMN-lite server container
• its own Postgres container
• its own Docker network
• its own Docker volume

Run the harness against a specific isolated instance:

cd bpmn-lite
cargo run -p xtask -- docker-smoke \
  --instance-name alpha \
  --server-port 50071 \
  --db-port 5541

Keep the containers running after the harness:

cd bpmn-lite
cargo run -p xtask -- docker-stress \
  --instance-name beta \
  --server-port 50072 \
  --db-port 5542 \
  --keep-running \
  --instances 200

Tear down a specific instance cleanly:

cd bpmn-lite
cargo run -p xtask -- docker-down --instance-name alpha

These Docker flows still use the same copy-by-value SessionStackState contract. The harness can mock session-stack values freely; BPMN-lite persists its own copies inside the instance/job records and does not depend on ob-poc database state.

Release Checklist

• env RUSTC_WRAPPER= cargo check
• env RUSTC_WRAPPER= cargo check -p xtask
• cargo run -p xtask -- docker-up --instance-name alpha --server-port 50071 --db-port 5541
• cargo run -p xtask -- docker-up --instance-name beta --server-port 50072 --db-port 5542
• cargo run -p xtask -- smoke --server-url http://127.0.0.1:50071
• cargo run -p xtask -- smoke --server-url http://127.0.0.1:50072
• Verify process_instances row counts independently in each paired Postgres instance.
• cargo run -p xtask -- docker-down --instance-name alpha
• cargo run -p xtask -- docker-down --instance-name beta
• Confirm docker ps -a shows no leftover BPMN-lite test containers.

Expected result:

• each BPMN-lite deployment migrates and serves against its own database
• the smoke harness passes independently against multiple live instances
• SessionStackState is copied by value into BPMN-owned persistence and is not shared by DB reference