Safeguard Work-Order Agent Ecosystem

Spec · Actioner

Agent Spec — Actioner

Status: implemented (against LIVE infrastructure) Source: src/agents/actioner.mjs Owner interface: async action(order, classification, routing, validation, env) -> result

Purpose

The decision point that realizes the program goal — **reduce human-in-the-loop to exception handling only**. The actioner is the only agent that performs side effects, and it always writes an audit entry so every automatic action is reconstructable.

Interface

action(order, classification, routing, validation, env) -> {
  action:       'AUTO_DISPATCH' | 'HUMAN_EXCEPTION' | 'REJECTED'
  dispatchRef?: string
  reason:       string
  payload?:     DispatchPayload
}

env = { gateway, repository }   // the gRPC + persistence seams

Decision table

Validation status	Action	Side effects
`VALID`	`AUTO_DISPATCH`	build contract payload → `gateway.dispatch` → persist record + audit
`VALID` but gateway rejects payload	`HUMAN_EXCEPTION`	persist + audit (never silently drop)
`NEEDS_REVIEW`	`HUMAN_EXCEPTION`	persist + audit with violation reasons
`REJECT`	`REJECTED`	persist + audit with blocking reasons

Dispatch payload contract

Every AUTO_DISPATCH builds a payload whose keys are exactly schema.DISPATCH_PAYLOAD_FIELDS and nothing else. The gRPC gateway validates this contract and rejects anything malformed — mirroring a real protobuf message boundary.

Guarantees

No silent drops. A payload the gateway refuses becomes a human exception,

not a lost order.

Idempotent. Dispatch is keyed on workOrderId; a retry returns the same

dispatch ref and never double-dispatches (verified).

Always audited. Exactly one append-only audit entry per processed order.

Integration (EXTERNAL LIVE)

env.gateway is a real gRPC client calling a running DispatchService (proto/dispatch.proto) over HTTP/2 — in the verified run, the external Go service in dispatch-service/. env.repository is a real PostgreSQL repository backed by an external PostgreSQL server (DATABASE_URL). Idempotency, malformed rejection, persistence, audit, and reconnect-after-restart are verified against the external stack. Remaining seams: Oracle (Postgres verified), the LLM classifier, and security controls. See proof/LIMITATIONS.md.