Download the PHP package milpa/orchestrator without Composer

# Milpa Orchestrator > **Event-sourced process orchestration** for the Milpa PHP framework: **everything is a process**, a process is a state machine, and **state is a projection of an append-only log**. Human gates carry live decision surfaces whose options map **1:1** to the process's own transitions; self-approval is refused by construction; three MCP tools drive it all. The greenhouse (`example-agent-ready-blog`) proved the loop before this package froze the contracts. [](https://github.com/getmilpa/orchestrator/actions/workflows/ci.yml) [](https://packagist.org/packages/milpa/orchestrator) [](https://www.php.net/) [](LICENSE) [](https://getmilpa.github.io/orchestrator/) `milpa/orchestrator` is the process engine of the Milpa family. It takes a `milpa/workflow` state machine — states, transitions, and human gates — and runs it as an **event-sourced process**: nothing stores `current_state`, every read replays an append-only log through a pure reducer, and human decision points surface as `milpa/live` components whose options can never drift from the transitions they actually resolve. It has **no ORM, no HTTP kernel, no product coupling** — the domain (a blog post, an invoice, a support ticket) lives entirely in the consumer's decision-surface factory and its `process.terminal` listener. ## Install ## The thesis Two ideas hold the whole engine together: 1. **Everything is a process, and a process is a state machine.** A `ProcessDefinition` is a set of `milpa/workflow` `StateDefinition`s wired by `TransitionDefinition`s, exactly one marked initial. A state whose outgoing transitions carry a `GateDefinition` is a **human decision point**; every other state advances automatically. 2. **State is a projection of the log, never a stored field.** Starting or advancing a process only ever *appends events* to an `EventStoreInterface`. The current state is whatever the pure `Reducer` folds those events into — recomputed fresh on every read. Two handles built from the same instance id over the same log always agree, and neither can cache a stale answer. Everything else — the auto-advancing runner, the human gate, the three MCP tools — is built on those two invariants. ## Quick example Define a three-state publishing process — `draft → review → published`, with a human gate on `review` and a `reject` transition that loops back to `draft` for revision: Wire the engine and expose it through the three tools: Now drive the loop — instantiate, hit the gate, submit a decision, reach terminal, and prove the state was never stored by replaying it from a fresh log: Had the editor chosen `reject`, the runner would have driven `review --reject--> draft --submit--> review` and re-opened a fresh gate — the revise-and-resubmit loop, all inside that one `process_submit_decision` call. (This exact loop is exercised end to end in `tests/ProcessLoopTest.php`.) ## Composes the family The orchestrator writes almost no primitives of its own — it *composes* the packages below the process tier and adds only the folding, running, and gating that turn them into a process engine: | Package | Role in a process | |---------|-------------------| | [`milpa/event-store`](https://packagist.org/packages/milpa/event-store) | **The log.** Every start, transition, gate opening, and decision is an `Event` appended to an `EventStoreInterface`. The engine stores nothing else. | | [`milpa/workflow`](https://packagist.org/packages/milpa/workflow) | **The gates + self-approval rule.** `ProcessDefinition` is built from workflow `StateDefinition`/`TransitionDefinition`/`GateDefinition`; `HumanGate` delegates the D9 anti-self-approval check to workflow's `GateServiceInterface` rather than reimplementing it. | | [`milpa/live`](https://packagist.org/packages/milpa/live) | **The decision surfaces.** A `DecisionSurfaceInterface` is a `milpa/live` component whose `options()` must equal the gate's transitions 1:1 — `PendingDecision`'s constructor enforces that invariant, so a stale artifact fails loudly instead of offering actions the gate does not have. | | [`milpa/tool-runtime`](https://packagist.org/packages/milpa/tool-runtime) | **The three MCP tools.** `process_instantiate`, `process_list_pending_approvals`, and `process_submit_decision` are `#[Tool]`-attributed methods that run through the tool-runtime pipeline like any other agent-callable tool. | | [`milpa/events`](https://packagist.org/packages/milpa/events) | **The reducer/terminal seam.** The reference `MilpaEventDispatcherInterface` implementation; `ProcessRunner` dispatches `process.terminal` through it exactly once per instance, where a consumer runs whatever domain effect reaching a terminal state should trigger. | Because the engine is domain-agnostic, the two things it does **not** own are exactly the two a consumer supplies: a `DecisionSurfaceFactoryInterface` (what a gate's surface renders for its domain) and a `process.terminal` listener (what reaching a terminal state *does*). ## Proven in a greenhouse Before these contracts were frozen, the whole loop was grown and validated inside **`example-agent-ready-blog`** — the family's greenhouse — as a real `PublishPostProcess`: an agent drafts a post, submits it, a human editor approves or rejects it through a live decision surface, and reaching `published` actually publishes the post via a `process.terminal` listener. This package is that proven loop, lifted out domain-free: the greenhouse kept the blog; the orchestrator kept the engine. ## Requirements - PHP **≥ 8.3** - [`milpa/core`](https://packagist.org/packages/milpa/core) **^0.6** - [`milpa/event-store`](https://packagist.org/packages/milpa/event-store) **^0.1** - [`milpa/workflow`](https://packagist.org/packages/milpa/workflow) **^0.1.2** - [`milpa/events`](https://packagist.org/packages/milpa/events) **^0.2** - [`milpa/live`](https://packagist.org/packages/milpa/live) **^0.1** - [`milpa/tool-runtime`](https://packagist.org/packages/milpa/tool-runtime) **^0.5.1** ## Documentation **Full API reference: [getmilpa.github.io/orchestrator](https://getmilpa.github.io/orchestrator/)** — generated straight from the source DocBlocks and dressed with the Milpa design system. ## Contributing Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Please report security issues via [SECURITY.md](SECURITY.md), and note that this project follows a [Code of Conduct](CODE_OF_CONDUCT.md). ## License [Apache-2.0](LICENSE) © Rodrigo Vicente - TeamX Agency. --- Milpa is designed, built, and maintained by **[Rodrigo Vicente - TeamX Agency](https://teamx.agency/?utm_source=github&utm_medium=readme&utm_campaign=milpa&utm_content=orchestrator)**.