R9 Work & Supply network (message protocol v1)

DSLCore applications and the orchestrator running a business process together, with no hand-written adapters: Work Management needs a part, Inventory reserves it or reports it unavailable, Purchasing raises a purchase requirement for what is unavailable and later tells Work when the supplier will deliver — all through the orchestrator, with retries, dead letters and an audit trail. Catalogue owns the item definitions the others look up; Supplier owns who they buy from, their approvals and their performance; SAP AP (a simulator) posts the commitments, matches supplier invoices against the order and the accepted goods, posts AP and records payment.

flowchart LR
  W["Work Management<br/>:5087"] -- publish --> O(("Orchestrator R9<br/>:5089"))
  I["Inventory<br/>:5088"] -- publish --> O
  O -- "work.material_requirement_created" --> I
  O -- "inventory.item_reserved / item_unavailable" --> W
  O -- "inventory.item_unavailable / receipt_*" --> P["Purchasing<br/>:5090"]
  P -- publish --> O
  O -- "purchasing.requirement_created / delivery_*" --> W

  W -. "item lookups (direct)" .-> C["Catalogue<br/>:5091"]
  I -. "item lookups (direct)" .-> C
  P -. "item lookups (direct)" .-> C
  O -- "order_placed / delivery_delayed / receipt_rejected" --> S["Supplier<br/>:5092"]
  P -. "supplier lookups (direct)" .-> S
  I -. "supplier lookups (direct)" .-> S
  O -- "order_placed / receipt_rejected / _quarantined" --> F["SAP AP (sim)<br/>:5093"]
  F -- "commitment_posted" --> O
  F -. "order + receipts (direct, at match time)" .-> P
  F -. " " .-> I
  O -- "work.component_removed" --> AR["Asset Register<br/>:5094"]
  W -. "asset lookups (direct)" .-> AR
  O -- "asset.component_installed / _removed" --> L["Asset Lifecycle<br/>:5095"]
  O -- "asset.component_removed / credit_memo_posted" --> X["Warranty<br/>:5096"]
  X -. "component exposure (direct)" .-> L
  O -- "material events (evaluated)" --> G["Assurance<br/>:5097"]
  G -- "obligation_assigned" --> O

Full network map — every message, who publishes / subscribes / accepts it, its fields, what is implemented, entity ownership and the reference flows: NETWORK_MAP.md (generated from the manifest and the contracts: python -m codegen.cli network-docs work_supply).

Member	Role	Code
`work_management` (5087)	owns work orders and material requirements	`apps/work_management/`
`inventory` (5088)	owns stock locations, reservations, goods receipts	`apps/inventory/`
`catalogue` (5091)	owns item definitions, identifiers, substitutes, fitment rules (R10)	`apps/catalogue/`
`orchestrator_r9` (5089)	routes and delivers messages (sandbox instance of `apps/orchestrator`, own DB)	`apps/orchestrator/`
`purchasing` (5090)	owns purchase requirements, orders, delivery commitments, shipments (R10.3)	`apps/purchasing/`
`supplier` (5092)	owns suppliers, capabilities, approvals, supplier items, supplier issues (R10.4b)	`apps/supplier/`
`asset_register` (5094)	owns assets, types / models, sites, component installations (R11.1)	`apps/asset_register/`
`asset_lifecycle` (5095)	owns usage meters, life models, component life forecasts, deratings (R11.2)	`apps/asset_lifecycle/`
`warranty` (5096)	owns warranty entitlements, candidates, claims, recoveries (R11.3)	`apps/warranty/`
`assurance` (5097)	owns governance exceptions, risks, decisions, obligations, verifications; materiality rules (R11.4)	`apps/assurance/`
`sap_ap` (5093)	finance simulator: commitments, supplier invoices, invoice matches, AP documents, payment status, credit memos (R10.4c)	`apps/sap_ap/`

Run it

python networks/work_supply/network.py start      # status | stop [--force] | restart | reset [--start] | --only <member>
python networks/work_supply/trigger.py r2         # oil filter x2  -> reserved
python networks/work_supply/trigger.py r1         # transmission x1 -> unavailable -> purchase requirement PR-…
python networks/work_supply/trigger.py r1c        # PO-004411 shipped, arrives, accepted -> WO-1001 resumes
python networks/work_supply/trigger.py p2p        # then: invoiced, matched, AP posted, paid (SAP AP)
python networks/work_supply/trigger.py warranty   # failed transmission claimed, credited in SAP AP, recovered

Step by step, what to look at and how to reset: RUNBOOK.md. The same flows run automatically, without servers, in server/tests/r9_acceptance/.

Files

File	What
`system.manifest.yaml`	the network: members, what each owns / publishes / consumes / accepts / answers, delivery policy, reference `flows:`; plus local-run settings (`orchestrator.instance`)
`NETWORK_MAP.md`	generated map, message catalogue, ownership and flow diagrams — regenerate after changing the manifest or a contract
`network.py`	start / stop / status / reset (wraps `networks/run_network.py`); member databases are generated from the apps' seed files, not kept in git
`load_network.py`	loads the manifest into the orchestrator DB (members, owners, subscriptions, retry policy) — run automatically by `network.py start`
`trigger.py`	starts an R1 / R2 flow and prints the outcome
`RUNBOOK.md`	the manual walkthrough
`logs/`	process output and PIDs (gitignored)

How the pieces are made

Layer	Source	Generated by
Screens, models, CRUD	`apps/<app>/schema/<app>.dsl`	`python -m codegen.cli all <app>`
Network contract	`apps/<app>/schema/<app>.integration.dsl` + `.integration.yaml`	`python -m codegen.cli integration <app> --network work_supply` (checks the manifest too)
Message handling	`apps/<app>/integration/handlers.py`	scaffolded once, then hand-written
Runtime	`server/lib/integration/` (apps), `server/lib/orchestrator_engine/messages.py` (orchestrator)	—

Rules for writing the DSL / YAML: docs/implementation/integration_authoring_spec.md. Design and as-built notes: docs/implementation/r9_integration_codegen.md.

Relationship to `networks/work_supply_00/`

That folder is the older entity-sync demo (mwem / msam / psam / scrm and the O&G apps on the 5086 sandbox orchestrator: routes and field mappings, no message contracts). The two networks use the same orchestrator code but separate instances and databases, and the same launcher (run_network.py). The older apps move to the message protocol in a later stage (R13).

What comes next

R10 added Catalogue (R10.1), the item picker on forms (R10.2), the real Purchasing app replacing the R9 stub (R10.3), goods arrival (R10.4a), Supplier (R10.4b) and the SAP AP simulator (R10.4c). R11 added the Asset Register, Asset Lifecycle, Warranty and Assurance — every application the contracts refer to is now a member. Next: R12, load testing and app testing with larger, more complex data runs. Deployment to the droplet (always-on orchestrator, live database migration) follows.