Reference Deployment

This is the production-directed alpha reference deployment for ACGP.

The shipped v1.0.0-alpha.2 reference deployment uses PostgreSQL-compatible runtime state for shared and production-oriented operation. SQLite remains useful for local development, tests, and single-node fallback workflows, but it is not the production runtime-state backend in the reference path.

It uses one supported cross-language story:

  • evaluator service running the canonical Python runtime
  • PostgreSQL for centralized audit metadata and request records
  • PostgreSQL-backed runtime state for the reference production path
  • health and metrics endpoints for operations
  • a TypeScript client example that calls the service boundary

Start Here

Use the repository assets under deploy/reference/.

The stack is started with:

docker compose -f deploy/reference/docker-compose.yml up --build

What This Deployment Proves

  • a non-Python app can call a supported evaluator service
  • the evaluator service runs the Python GovernanceSteward
  • centralized audit records are persisted in PostgreSQL
  • centralized runtime state is persisted in PostgreSQL
  • the service exposes health and metrics endpoints suitable for staging and production-like operations

Topology

flowchart LR
    App[TS or non-Python app] --> Service[Evaluator service :8080]
    Service --> Steward[Python GovernanceSteward]
    Steward --> PostgresState[(PostgreSQL runtime state)]
    Service --> Postgres[(PostgreSQL)]

Local

For local development, use the compose file as-is.

  • default service endpoint: http://127.0.0.1:8080/evaluate
  • health endpoint: http://127.0.0.1:8080/healthz
  • readiness endpoint: http://127.0.0.1:8080/readyz
  • metrics endpoint: http://127.0.0.1:8080/metrics
  • observability endpoint: http://127.0.0.1:8080/observability
  • HITL completion endpoint: http://127.0.0.1:8080/hitl/complete

Staging

For staging, keep the reference topology but replace local defaults.

  • use a non-default bearer token or internal auth gateway
  • run PostgreSQL as a managed or separately operated service
  • place the evaluator service behind TLS termination
  • point ACGP_RUNTIME_STATE_DSN at the managed PostgreSQL service

Production-ish

For a production-like rollout, add the expected operational controls.

  • run multiple evaluator-service replicas behind an internal load balancer
  • restrict ingress to trusted internal callers only
  • scrape /metrics into Prometheus or another metrics backend
  • ingest /observability into your governance telemetry pipeline for the canonical acgp_observability_v1 report shape
  • route hitl_request metadata from /evaluate into an operator review queue and post reviewer decisions to /hitl/complete
  • keep large evidence blobs in object storage and store references in PostgreSQL
  • monitor PostgreSQL availability and backup/restore posture independently from the evaluator service

Current Alpha Boundaries

This reference deployment is intentionally honest about backend maturity.

  • PostgreSQL is the shipped centralized production database for audit metadata and runtime state in this reference deployment.
  • PostgresStateStorage is the packaged production runtime-state backend in the Python SDK.
  • SQLiteStateStorage remains the developer and single-node durable backend outside the shipped reference deployment path. PostgreSQL remains the centralized production runtime-state path.