Cross-cluster contracts
Integration through contracts, not spaghetti dependencies. Each has a producer, a consumer, a version, a field-level schema and a statement of how both sides keep working when the other is absent. Status proposed means documented here and nowhere else.
OperationalEvent v0.1.0proposed
Energy Intelligence (e.g. GridOS) detects an asset anomaly and emits an operational event. Operations (Runway Fuel or a vertical) may convert it into a work order.
| Field | Type | Meaning |
|---|---|---|
eventId | string (UUID) | Idempotency key; a consumer that sees it twice does nothing the second time. |
emittedAt | string (RFC 3339) | Producer clock, UTC. |
producer | "energy" | Cluster of origin. Fixed per contract. |
assetRef | string (URI) | Opaque reference into the producer’s asset registry. The consumer never resolves it against a shared database. |
kind | "anomaly" | "threshold" | "outage" | "maintenance-due" | Closed set; new kinds bump the minor version. |
severity | "info" | "warning" | "critical" | Producer’s assessment. The consumer decides what a work order is worth. |
summary | string ≤ 280 | Human-readable, for the work-order title. |
evidenceUrl | string (URL) | null | Where the producer keeps the detail. Optional; the event is complete without it. |
Independence. Energy runs with no consumer subscribed. Operations runs with no producer: work orders are also created by hand and by the verticals’ own triggers.
WorkOrder v0.1.0proposed
Operations issues a work order — an inspection, a pick, a paint pass — that Physical AI may execute with its own planning, simulation, safety and authorization chain. Operations never commands an actuator.
| Field | Type | Meaning |
|---|---|---|
workOrderId | string (UUID) | Idempotency key. |
createdAt | string (RFC 3339) | Operations clock, UTC. |
originEventId | string (UUID) | null | The OperationalEvent that caused it, if any. |
task | "inspection" | "palletize" | "surface-finish" | "other" | Closed set of task families Physical AI recognizes. |
siteRef | string (URI) | Opaque site or cell reference. |
window | { notBefore, notAfter } | Execution window. Outside it the order expires without action. |
approval | { approvedBy, approvedAt } | A human approved the order in Operations. Required; a work order without approval is invalid by schema. |
callbackUrl | string (URL) | Where the result is delivered. Operations polls if the callback fails. |
Independence. Physical AI accepts work orders from any source including a human console. Operations keeps a work order in state "awaiting-executor" indefinitely if no executor exists.
InspectionResult v0.1.0proposed
Physical AI returns the result of an executed work order. Energy Intelligence attaches it to the asset that raised the original event. Operations receives a copy to close the work order.
| Field | Type | Meaning |
|---|---|---|
resultId | string (UUID) | Idempotency key. |
workOrderId | string (UUID) | The WorkOrder executed. |
completedAt | string (RFC 3339) | Executor clock, UTC. |
outcome | "completed" | "partial" | "aborted" | "failed-safe" | Closed set. "failed-safe" means the safety chain stopped execution — always reported, never hidden. |
findings | Finding[] | Each with classification, localization and confidence. Empty array is a valid result. |
evidence | Artefact[] | Images, point clouds, logs, by URL with hash. |
interventions | number | Human interventions during execution. A KPI for Physical AI; a cost input for Operations. |
Independence. Energy treats a missing result as "no inspection performed" and keeps its own anomaly open. Operations closes work orders manually if no executor reports.