pg_play-integration.md

pg_play integration contract

This document is for orchestrator authors. Normal users retain the report, render, inspect, and collection CLI documented in the README.

pg_diag supports the hidden pg_play/component/v1 machine transport:

pg-diag --machine --request-id diag-001 --component-capabilities
pg-diag --machine --request-id diag-002 explain-plan \
  --pg-version 180000 --run-mode snapshots --collection-mode remote-db-only
pg-diag --machine --request-id diag-003 validate-artifact report.json
pg-diag --machine --request-id diag-004 summarize report.json
pg-diag --machine --request-id diag-005 configuration-facts report.json \
  --out configuration-facts.json

The capability document uses pg_play/capabilities/v1. Every command declares the common boolean fields mutates_target, machine_output, and accepts_plan_hash. Its machine_interface object records the canonical machine, request-id, and capability option names.

One-shot and snapshots collection commands also return the common machine envelope. Report files are described by paths and SHA-256 hashes. Partial collection remains partial; it is not promoted to success merely because a JSON artifact exists.

summarize validates the artifact schema before returning deterministic counts, completeness, severities, collection statuses, snapshot count, and fallback degradation. A successful replacement may keep completeness at 100% and has_errors false while setting degraded: true; fallback_items lists the affected parent IDs, triggers, and final statuses. It does not interpret findings or apply remediation.

configuration-facts validates the source report and extracts the stable pg_diag/configuration-facts-v1 subset used by configuration tools. The facts artifact preserves its source hash and item completeness. Missing CPU, RAM, server-version, or pg_settings items make collection.usable false instead of silently substituting host-local defaults.