feat: add pg_converter orchestration

Author: O2eg

.github/workflows/publish.yml

@@ -51,7 +51,7 @@ jobs:
           "${RUNNER_TEMP}/pg-play-wheel-smoke/bin/python" -m pip install dist/*.whl
           "${RUNNER_TEMP}/pg-play-wheel-smoke/bin/python" -m pip check
           "${RUNNER_TEMP}/pg-play-wheel-smoke/bin/pg-play" capabilities
-          for command in pg-configurator pg-diag pg-perf-bench pg-stand pg-workload; do
+          for command in pg-configurator pg-converter pg-diag pg-perf-bench pg-stand pg-workload; do
             "${RUNNER_TEMP}/pg-play-wheel-smoke/bin/${command}" --version
           done
       - name: Upload distributions for publishing

.github/workflows/tests.yml

@@ -28,6 +28,10 @@ jobs:
         with:
           repository: O2eg/pg_configurator
           path: .ci-components/pg_configurator
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          repository: O2eg/pg_converter
+          path: .ci-components/pg_converter
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
         with:
           repository: O2eg/pg_diag
@@ -51,6 +55,7 @@ jobs:
         run: |
           python -m pip install \
             --editable .ci-components/pg_configurator \
+            --editable .ci-components/pg_converter \
             --editable .ci-components/pg_diag \
             --editable .ci-components/pg_perf_bench \
             --editable .ci-components/pg_stand \
@@ -71,6 +76,10 @@ jobs:
         with:
           repository: O2eg/pg_configurator
           path: .ci-components/pg_configurator
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          repository: O2eg/pg_converter
+          path: .ci-components/pg_converter
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
         with:
           repository: O2eg/pg_diag
@@ -99,6 +108,7 @@ jobs:
           python -m venv "${RUNNER_TEMP}/pg-play-wheel-smoke"
           "${RUNNER_TEMP}/pg-play-wheel-smoke/bin/python" -m pip install \
             --editable .ci-components/pg_configurator \
+            --editable .ci-components/pg_converter \
             --editable .ci-components/pg_diag \
             --editable .ci-components/pg_perf_bench \
             --editable .ci-components/pg_stand \
@@ -107,6 +117,6 @@ jobs:
           "${RUNNER_TEMP}/pg-play-wheel-smoke/bin/python" -m pip check
           "${RUNNER_TEMP}/pg-play-wheel-smoke/bin/pg-play" --version
           "${RUNNER_TEMP}/pg-play-wheel-smoke/bin/pg-play" capabilities
-          for command in pg-configurator pg-diag pg-perf-bench pg-stand pg-workload; do
+          for command in pg-configurator pg-converter pg-diag pg-perf-bench pg-stand pg-workload; do
             "${RUNNER_TEMP}/pg-play-wheel-smoke/bin/${command}" --version
           done

README.md

@@ -14,6 +14,8 @@ experiments.
   collection as a successful complete run.
 - Plans and runs `pg_perf_bench` only against an explicitly selected disposable
   database, then validates and compares benchmark artifacts and TPS evidence.
+- Plans and runs reviewed `pg_converter` packets against an exact alias set
+  through a detached, auditable, sequential workflow.
 - Installs every component while preserving their independent use.
 
 The independently installable components are:
@@ -25,7 +27,9 @@ The independently installable components are:
 - [`pg_diag`](https://github.com/O2eg/pg_diag) — diagnostic JSON and HTML
   artifacts;
 - [`pg_configurator`](https://github.com/O2eg/pg_configurator) — version-aware
-  PostgreSQL configuration candidates.
+  PostgreSQL configuration candidates;
+- [`pg_converter`](https://github.com/O2eg/pg_converter) — reviewed SQL/Python
+  packet deployment and migration operations;
 - [`pg_perf_bench`](https://github.com/O2eg/pg_perf_bench) — controlled pgbench
   execution and environment evidence.
 
@@ -43,13 +47,13 @@ The independently installable components are:
           pg_stand ------------------------+
               |
               v
-                    PostgreSQL stand
-                  /          |          \
-                 v           v           v
-          pg_workload  pg_perf_bench   pg_diag
-                 |           |           |
-                 |     benchmark report  |
-                 +--------- run ----------+----> diagnostic report
+                         PostgreSQL stand
+                 /          /      \          \
+                v          v        v          v
+       pg_converter  pg_workload  pg_perf_bench  pg_diag
+                |          |        |             |
+          packet run       |  benchmark report   |
+                +----------+------ run -----------+----> diagnostic report
                                   |
                   change one reviewed input
                                   |
@@ -62,7 +66,7 @@ The control layers are deliberately separate:
 agent skills          workflow and interpretation rules
       |
       v
-pg-play-mcp           twenty-six typed, high-level operations
+pg-play-mcp           thirty-one typed, high-level operations
       |
       v
 pg_play core          validation, planning, state, comparison
@@ -71,6 +75,7 @@ pg_play core          validation, planning, state, comparison
 component adapters    argv arrays + strict JSON envelopes
       |
       +---- pg_configurator
+      +---- pg_converter
       +---- pg_stand
       +---- pg_workload
       +---- pg_diag
@@ -87,14 +92,15 @@ are hidden from its primary help and its normal human output is unchanged.
 python -m pip install pg-play
 ```
 
-This installs compatible versions of all five component distributions. They
+This installs compatible versions of all six component distributions. They
 remain available through their own commands:
 
 ```bash
 pg-stand --help
 pg-workload --help
 pg-diag --help
 pg-configurator --help
+pg-converter --help
 pg-perf-bench --help
 ```
 
@@ -208,7 +214,7 @@ The packaged JSON Schema is available as the MCP resource
 Secrets are the deliberate exception: `pg_workload` continues to accept
 passwords only through environment/passfile mechanisms.
 
-All five components use the same hidden orchestration options:
+All six components use the same hidden orchestration options:
 `--machine`, `--request-id`, and `--component-capabilities`. Their advertised
 `machine_interface` object makes these names machine-verifiable.
 
@@ -219,6 +225,11 @@ The `pg-play` CLI contains only complete experiment operations:
 | Command | Effect |
 | --- | --- |
 | `capabilities` | Read installed component contracts |
+| `plan-converter-run --project DIR --config FILE --packet NAME` | Resolve packet content and exact database aliases without connecting |
+| `start-converter-run PLAN.json --plan-hash HASH --out DIR --run-id ID` | Start an unchanged packet plan in a detached worker |
+| `converter-run-status RUN_DIR` | Read durable packet-run state and detect a lost worker |
+| `converter-run-events RUN_DIR [--after-sequence N]` | Read ordered packet-run events |
+| `cancel-converter-run RUN_DIR [--reason TEXT]` | Request cooperative packet cancellation |
 | `validate MANIFEST` | Validate the manifest and non-mutating component inputs |
 | `plan MANIFEST` | Calculate the current read-only plan and its hash |
 | `start MANIFEST --plan-hash HASH --run-id ID` | Start exactly that plan in a detached worker and return immediately |
@@ -262,6 +273,40 @@ for a verified failed, cancelled, or interrupted attempt; use a new id when the
 manifest or plan changes. `run` retains the old synchronous behavior for
 scripts that explicitly need it.
 
+### Reviewed pg_converter packet runs
+
+`pg_converter` packets are trusted deployment code and are intentionally
+separate from the general experiment manifest. Plan an exact packet, review
+its legacy tracker checksum, SHA-256 source-tree hash, Python-step flag, and
+resolved database aliases and password-free connection identities, then start
+the unchanged plan:
+
+```bash
+pg-play plan-converter-run \
+  --project /opt/pg_converter/current \
+  --config /etc/pg_converter/pg_converter.conf \
+  --packet release_42 \
+  --database-selector 'prod_a,prod_b' \
+  --placeholders-file /run/pg_converter/release_42.json \
+  --timeout-seconds 3600 > converter-plan.json
+
+pg-play start-converter-run converter-plan.json \
+  --plan-hash sha256:... \
+  --out /var/lib/pg_play/converter-runs \
+  --run-id release-42
+```
+
+The machine path always uses sequential database processing and never enables
+`--force`, `--wipe`, `--stop`, `--unlock`, template copying, or skip-on-cancel
+modes. The reviewed plan replaces only the interactive multi-database prompt;
+it does not bypass PG Converter checksum or ambiguous-outcome safeguards.
+Credentials stay in the protected configuration file. Placeholder and
+configuration-override values are accepted only through protected JSON files
+and are represented in the plan by names and hashes, not values.
+See the
+[pg_converter integration runbook](https://github.com/O2eg/pg_play/blob/main/docs/pg_converter-integration.md)
+for the durable directory, cancellation, and recovery contracts.
+
 ## MCP server
 
 Start the stdio server with:
@@ -278,6 +323,11 @@ for concise MCP and Agent Skills configuration examples for Codex CLI, Claude
 Code, Hermes Agent, Kimi Code CLI, Gemini CLI, and OpenCode.
 
 - `component_capabilities`
+- `plan_converter_run`
+- `start_converter_run`
+- `converter_run_status`
+- `converter_run_events`
+- `cancel_converter_run`
 - `plan_live_diagnostics`
 - `start_live_diagnostics`
 - `live_diagnostics_status`
@@ -314,11 +364,20 @@ and intentionally excludes the 2.x prerelease API.
 The durable schemas are also exposed as `pgplay://run-state-schema` and
 `pgplay://run-event-schema`.
 
+For packet deployment, an agent must call `plan_converter_run`, show the exact
+packet/source hashes, target aliases, Python-step risk, and mutation flags to
+the user, and pass the unchanged plan and hash to `start_converter_run`.
+Observe it through `converter_run_status` and `converter_run_events`. A failed
+or interrupted packet is not automatically retried because non-transactional
+actions can have an ambiguous outcome.
+
 ## Agent skills
 
-The wheel contains five optional workflow skills under `pg_play/skills/`:
+The wheel contains six optional workflow skills under `pg_play/skills/`:
 
 - `run-postgres-experiment` — validate, plan, start, and monitor a new run;
+- `run-pg-converter-packet` — review exact packet sources and targets, start
+  the immutable run, and preserve ambiguous outcomes for operator recovery;
 - `recover-postgres-experiment` — inspect, cancel, and safely resume an
   existing durable run;
 - `diagnose-live-postgres` — capture a bounded, read-only diagnostic window on
@@ -431,6 +490,8 @@ unknown step or changed core artifact blocks recovery.
   combined plan hash. `start` and `resume` enforce the same hash. Machine-mode
   `pg_perf_bench benchmark` independently
   verifies a content-sensitive benchmark plan hash before resetting its database.
+- `pg_converter run` independently verifies the reviewed component plan hash,
+  including the exact alias set, packet source tree, and file-based inputs.
 - Subprocesses receive argument arrays with `shell=False`.
 - Password-bearing CLI arguments and password-bearing machine output are
   rejected.
@@ -456,22 +517,25 @@ read-only profiles and one bounded snapshots window per immutable capture id.
 Configuration review extracts the bounded CPU, RAM, filesystem, mount, and disk
 facts listed above. Generation or application of TuneD/systemd artifacts remains
 a roadmap item; it is not silently approximated by the current implementation.
+Reviewed `pg_converter` runs are a separate durable workflow and are not
+silently injected into every experiment manifest.
 
 ## Development
 
 ```bash
 python3 -m venv .venv
 .venv/bin/pip install -e ../pg_stand -e ../pg_workload -e ../pg_diag \
-  -e ../pg_configurator -e ../pg_perf_bench
+  -e ../pg_configurator -e ../pg_converter -e ../pg_perf_bench
 .venv/bin/pip install -e '.[dev]'
 .venv/bin/ruff check .
 .venv/bin/ruff format --check .
 .venv/bin/pytest
 ```
 
 For coordinated releases, publish the component distributions before tagging
-`pg_play`: first `pg_configurator`, `pg_diag`, `pg_stand`, and `pg_workload`,
-then `pg_perf_bench` (which depends on `pg_diag`), and finally `pg_play`.
+`pg_play`: first `pg_configurator`, `pg_converter`, `pg_diag`, `pg_stand`, and
+`pg_workload`, then `pg_perf_bench` (which depends on `pg_diag`), and finally
+`pg_play`.
 Ordinary branch CI checks out the component sources so a coordinated source
 change can be tested before those versions reach PyPI. Tagged publish jobs use
 the package index deliberately and therefore enforce this release order.

docs/pg_converter-integration.md

@@ -0,0 +1,117 @@
+# pg_converter packet runs through pg_play
+
+`pg_play` exposes a bounded, typed workflow for reviewed `pg_converter`
+packets. It does not expose raw component arguments, SQL, Python source,
+tracker deletion, backend termination, or `--force` through MCP.
+
+## Prerequisites
+
+- `pg_converter` and `pg_play` are installed in the same environment;
+- the packet project is available on the MCP server host;
+- the INI configuration and optional JSON input files are readable only by the
+  runtime account;
+- packet SQL/Python and its source-control revision were reviewed separately;
+- the selected role has only the PostgreSQL privileges the packet requires.
+
+The MCP server uses local file references. It does not accept a DSN, password,
+packet body, SQL string, or Python source in a tool call.
+
+## Plan
+
+Call:
+
+```text
+plan_converter_run(
+  project_directory,
+  config_file,
+  packet_name,
+  database_selector="ALL",
+  placeholders_file=null,
+  config_overrides_file=null,
+  timeout_seconds=3600
+)
+```
+
+The operation invokes only the non-connecting `pg_converter --plan` path.
+The result contains:
+
+- `pg_converter/plan-v1` with the exact alias set and password-free connection
+  identities;
+- the v1-compatible MD5 tracker checksum;
+- the SHA-256 packet-tree hash, including filenames and nested data;
+- step names and an explicit Python-step risk flag;
+- safe configuration and protected input-file hashes without credentials or
+  values;
+- a `pg_play/converter-run-plan-v1` wrapper and final `plan_hash`.
+
+Review at least the packet name/type, both hashes, database aliases,
+`execute_sql`, Python-step flag, tracker-initialization flag, and timeout.
+
+## Start and observe
+
+Pass the unchanged plan object and hash:
+
+```text
+start_converter_run(plan, plan_hash, output_directory, run_id)
+```
+
+`run_id` is immutable and may contain letters, digits, `_`, `-`, and `.`. The
+new run directory is created with mode `0700`; files use `0600`.
+
+The call returns after starting a detached worker. Continue with:
+
+```text
+converter_run_status(run_directory)
+converter_run_events(run_directory, after_sequence=0, limit=1000)
+```
+
+Use the returned `last_sequence` as the next cursor. Terminal states are
+`succeeded`, `partial`, `failed`, and `cancelled`. A vanished worker becomes
+`interrupted`.
+
+The run directory contains:
+
+```text
+RUN_ID/
+|-- plan.json
+|-- state.json
+|-- events.jsonl
+|-- result.json
+|-- worker.log
+|-- active-process.json       # only while the component is active
+`-- cancel.request.json       # only after cancellation is requested
+```
+
+`result.json` contains the common component envelope and compact
+`pg_converter/machine-result-v1`. Raw step result sets and connection strings
+are not copied into durable pg_play state. Machine execution forces SQL logging
+off. Export paths are also withheld because the legacy random-password export
+mode can embed its password in a filename; use the per-database export counts
+and inspect the protected packet directory as an operator.
+
+## Cancellation and recovery
+
+Call `cancel_converter_run(run_directory, reason)` only for an active run and
+provide a concise audit reason. `pg_play` records the request and terminates
+only the process whose PID start time, operating-system owner, and executable
+identity match the active-process record.
+
+There is deliberately no automatic resume tool for packet runs. Transactional
+actions retain PG Converter's tracker guarantees, but a non-transactional or
+maintenance action can finish with an ambiguous outcome. After `failed`,
+`cancelled`, or `interrupted`:
+
+1. inspect `state.json`, `events.jsonl`, `worker.log`, and target PostgreSQL;
+2. follow the PG Converter `outcome_unknown` and lock recovery runbooks;
+3. resolve target state explicitly;
+4. build and review a new plan before starting a new immutable run id.
+
+MCP cancellation does not authorize `wipe`, `unlock`, `stop`, or `force`.
+Those remain direct operator actions.
+
+## Agent Skill
+
+The wheel packages `run-pg-converter-packet`. It restricts an agent to the
+five typed converter tools, requires explicit authorization after showing the
+resolved endpoints and source hashes, and hands partial, failed, cancelled, or
+interrupted outcomes to an operator instead of retrying them.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pg-play"
-version = "0.2.1"
+version = "0.3.0"
 description = "MCP orchestrator for reproducible PostgreSQL performance experiments"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -31,6 +31,7 @@ classifiers = [
 dependencies = [
   "mcp>=1.28,<2",
   "pg-configurator>=0.9.1,<1",
+  "pg-converter>=2.0b2,<3",
   "pg-diag>=0.10.4,<1",
   "pg-perf-bench>=0.2,<1",
   "pg-stand>=0.2.1,<1",