Safeguard Work-Order Agent Ecosystem

Run & Deploy

Local run — external live services (recommended)

Requires Node ≥ 20 and Docker.

cd delivery-package/work-order-agents
npm install
docker compose up -d --build      # PostgreSQL 16 (host :5433) + Go gRPC (:50051)

# PowerShell
$env:DATABASE_URL="postgres://forge:forge@127.0.0.1:5433/workorders"
$env:DISPATCH_GRPC_URL="127.0.0.1:50051"
node verify.mjs        # 23 checks against external Postgres + Go gRPC
node server.mjs        # HTTP ingest API on :8080
node run.mjs --n 12    # process synthetic orders end-to-end

docker compose down -v # tear down

Self-contained fallback (no Docker)

node verify.mjs        # in-process PGlite + Node gRPC (21 checks)
node server.mjs        # in-process services, HTTP :8080

The live service

node server.mjs exposes:

POST /work-orders — ingest + process one order, returns its disposition
GET /work-orders/:id — persisted record + audit trail
GET /healthz — gRPC + DB liveness + active mode
GET /stats — repository row counts

Architecture of the external stack

HTTP (server.mjs, Node)
  → classify/route/validate (Node agents)
  → Actioner → gRPC ──wire──▶ Go DispatchService (dispatch-service/, container)
  → repository ──TCP──▶ PostgreSQL 16 (container)         ▲
                              ▲──────── dispatch_records ──┘

The Go service and the Node repository share the external Postgres.

Configuration (environment)

All knobs are environment-driven (src/config.mjs, .env.example):

Var	Default	Meaning
`DATABASE_URL`	(unset → PGlite)	external Postgres connection string
`DISPATCH_GRPC_URL`	(unset → in-process)	external gRPC dispatch address
`MIN_CATEGORY_CONFIDENCE`	0.55	classifier floor for auto-action
`MIN_PRIORITY_CONFIDENCE`	0.55	priority floor
`MAX_AUTO_APPROVE_COST`	5000	cost cap above which a human signs off
`DUPLICATE_WINDOW_MS`	86400000	duplicate-detection window
`SLA_P1_HOURS`/`SLA_P2_HOURS`/`SLA_P3_HOURS`/`SLA_P4_HOURS`	2 / 8 / base / base	SLA policy
`PORT` / `GRPC_PORT` / `DB_DIR`	8080 / 50051 / data/pg	ports + PGlite dir

Wiring to existing back-end systems

External Postgres / Oracle

Point DATABASE_URL at your Postgres. The repository (src/integrations/repository.mjs) uses standard $1 parameterized SQL. For Oracle, implement the same repository methods against an Oracle driver — no agent changes.

Go/gRPC dispatch service

The boundary is proto/dispatch.proto. The included Go service (dispatch-service/) is production-shaped; replace or extend it and point DISPATCH_GRPC_URL at your deployment.

Classifier engine (optional LLM swap)

Implement an LLM behind the existing classify() interface (specs/agent-classifier.md), preserving confidence + reasoning so the validator's safety behaviour is unchanged.

What is NOT production-hardened here

No auth/RBAC/tenant isolation, no TLS/mTLS (gRPC is insecure, Postgres uses a dev credential), no HA/load testing. See proof/LIMITATIONS.md for the full list and the path to PRODUCTION_VALIDATED.

CI gate (repo root, external services up)

(cd delivery-package/work-order-agents && npm install && docker compose up -d --build)
DATABASE_URL=postgres://forge:forge@127.0.0.1:5433/workorders \
DISPATCH_GRPC_URL=127.0.0.1:50051 \
node tools/forge-proof.mjs --outcome delivery-package/work-order-agents \
  --verify "node verify.mjs" --report verification-report.json
node tools/forge-gate.mjs --outcome delivery-package/work-order-agents --action commit