# sim.pflow.xyz

> Cost-benefit analysis for anything you can describe as a flow. Should I
> hire another barista, add a van, or build this feature? Describe the
> decision as a Petri net — staffing, queues, equipment, patience, or a
> backlog gated by cost-benefit review — store it with one POST, and every
> model gets the same instruments: seeded scenario comparison, disruption
> injection, calibration against your own event log, synthetic event-log
> datasets, model diagnostics that rank every knob by measured influence on
> the objective, and one-click publishing into your own Google Sheets with
> live charts. Models are content-addressed and immutable; scenarios are
> pure, seeded reads (same seed, same answer, byte for byte). The diagnostics
> pass has found capacity that *hurts* the objective as often as capacity
> that helps — a café's pantry stock, a hospital's ED bays, a software team's
> headcount — so "add more" gets checked instead of assumed.

Models are flat JSON: `{"name", "places": [{"id","initial",…}],
"transitions": [{"id","rate",…}], "arcs": [{"from","to","weight",…}]}` plus
optional declared metamodel blocks — `simulation.objective` (a numeric marking
expression the diagnostics rank on), `parameters` (arc weights or capacities
exposed as named knobs), `stages` on a transition (Erlang-k service time),
and `schedule` on a transition (a piecewise day shape carried by the model).
The discrete engine enforces read arcs, inhibitors, capacities, and
non-accelerating queues, and says plainly what it could not enforce.

## Docs

- [Full guide](https://sim.pflow.xyz/llms-full.txt): model format, the HTTP
  API per model, the MCP tools, the metamodel, Sheets publishing, showcases
- [Model JSON-LD context](https://sim.pflow.xyz/context/model/v1): every
  model-schema field as a linked-data term
- [Diagnosis/classification JSON-LD context](https://sim.pflow.xyz/ns/v1/context):
  the `@context` every diagnosis, classification and lineage document carries
- [Vocabulary](https://sim.pflow.xyz/ns/v1): glossary of load-bearing terms
  (isKinetic, capacity, ratePerHour, viewRole, rateOverrides, …)

## API

- [Catalog](https://sim.pflow.xyz/api/catalog): curated consoles plus every
  model dedicated to the commons (CC0/CC-BY), JSON, CORS-open
- [Models](https://sim.pflow.xyz/api/models): `POST` a model to store it;
  `GET /api/models/{id}` returns it (`Accept: application/ld+json` wraps it)
- Per-model reads (all seeded, all pure): `GET {id}/rates` (declared knobs),
  `POST {id}/scenario`, `POST {id}/scenario/compare`, `GET {id}/dataset`
  (`?seed=&cases=&format=csv|jsonl`), `GET {id}/diagnose`, `{id}/verify`,
  `{id}/invariants`, `{id}/crosscheck`, `{id}/evaluate`
- Per-model writes (owner, signed in): `POST {id}/calibrate` (event log →
  new calibrated model), `POST {id}/compose`, `POST {id}/publish` (→ your
  Google Sheets), `POST {id}/receipt` (Ed25519 signed run receipt),
  `POST {id}/license`, `DELETE {id}`
- [Components](https://sim.pflow.xyz/api/components): subnet templates
  (arrivals, service, hazard, inventory, decision, mailbox, datastore)
- [Receipt key](https://sim.pflow.xyz/api/receipts/key): public key for
  `POST /api/receipts/verify`

## MCP

- [MCP server](https://sim.pflow.xyz/mcp): Streamable HTTP, OAuth 2.1 with
  dynamic client registration (`/oauth/register`, `/oauth/authorize`,
  `/oauth/token`). Tools: sim_list_models, sim_get_model, sim_create_model,
  sim_delete_model, sim_license_model, sim_supersede_model, sim_components,
  sim_compose, sim_scenario, sim_compare, sim_dataset, sim_calibrate,
  sim_diagnose, sim_classify, sim_refine, sim_verify, sim_invariants,
  sim_crosscheck, sim_evaluate, sim_receipt, sim_publish, sim_publish_app,
  sim_my_sheets

## Consoles

- [Landing + catalog](https://sim.pflow.xyz/): every model, with Open
  console / Open app / Dataset / Publish to Sheets
- [What-if console](https://sim.pflow.xyz/whatif/?id=vet-clinic): generic
  console for any stored model id — knobs, disruptions, seeded comparison
- [Build a model](https://sim.pflow.xyz/build/): guided builder (sign-in)
- Published apps: `https://sim.pflow.xyz/app/{id}` — single-file HTML an
  owner published from the model's `view` prompt, served in a sandboxed origin

## Showcases (CC0, in the commons)

- [feature-lab](https://sim.pflow.xyz/whatif/?id=47db64e54d24ca0600360c8c):
  cost-benefit for software decisions — a backlog gated by cost-benefit
  evaluation, capacity-constrained engineering, a telemetry validate/kill
  measurement window, and an evolutionary feedback loop (validated features
  seed follow-on ideas). diagnose found more engineering capacity *hurting*
  the objective past a point — the same shape of finding this tool makes
  across any domain, not just software.
- [delivery-fleet](https://sim.pflow.xyz/whatif/?id=e38fc49777b731cfbc2764b9):
  declared objective — how many vans, scored on parcels minus van-hours
- [bakery-oven](https://sim.pflow.xyz/whatif/?id=830937feca631188b3c421ed):
  declared parameter — batch size as a structural knob
- [car-wash](https://sim.pflow.xyz/whatif/?id=735dd8109ce265a6de2c37a3):
  stages — predictable wash cycle as phase-type (Erlang-k) service
- [food-truck](https://sim.pflow.xyz/whatif/?id=5159060ebfc150ea61b8e7a6):
  schedule — the lunch rush as a model-carried day shape
- Curated: [vet-clinic](https://sim.pflow.xyz/whatif/?id=vet-clinic),
  [cafe](https://sim.pflow.xyz/whatif/?id=cafe),
  [predator-prey](https://sim.pflow.xyz/api/models/predator-prey)

## Related

- [pflow.xyz](https://pflow.xyz): visual Petri net editor and browser ODE /
  simulation modules (`https://pflow.xyz/llms.txt`)
- [pilot.pflow.xyz](https://pilot.pflow.xyz): analysis and code-generation
  MCP server (petri_ode, petri_rate_scan, petri_codegen, …)
- [book.pflow.xyz](https://book.pflow.xyz): the book on modeling with Petri nets

## Optional

- Run-receipt verification is public and needs no account:
  `POST /api/receipts/verify` replays the scenario and checks the signature
- `/healthz` is reserved at the Cloud Run edge; probe `/api/catalog` instead