pdurlej/platform

Fork 0

feat(platformctl): implement read-only plan drift check #159

Merged

pdurlej merged 1 commit from codex/issues/142-phase3-plan into main

2026-05-10 23:17:01 +02:00

codex commented

2026-05-10 03:43:00 +02:00

Collaborator

Canary status: missing — fire canary 3+3 manually before merge

Canary Context Pack

Product story

Phase 3 needs a read-only way to compare platform desired state with runtime state before RS2000 cutover work proceeds. This PR gives the operator a bounded drift signal for one module without applying anything to production.

What changed

platformctl plan <module> now fetches remote read-only state through TailscaleTransport by running docker inspect home-platform-<compose-service>-1.
Plan output compares container name, Docker Compose service label, running state, and image evidence against module.yaml.
--json emits the plan object; default output is compact human-readable text.
--out accepts either an explicit plan file path or an output directory.
Tests cover mocked transport success, drift detection, artifact writing, observation failure, and human output.

Why it changed

This is Packet 3.2 of the cutover flight. It moves platformctl plan from skeleton/no observation to a small real read-only inspection primitive, while keeping mutation for later gated packets.

Files touched

control-plane/platformctl/plan.py
control-plane/platformctl/cli.py
control-plane/platformctl/tests/test_plan_phase3.py

Relevant context

Tracking issue: #142
Stack base: PR #158 transport, which is stacked on PR #157 safety.
Master prompt: prompts/codex-cutover-flight/phase-3-operational.md Packet 3.2.
Existing CLI/control-plane prompt: prompts/03-control.md for the older platform-wide exit-code contract.

Runtime evidence

No production command was executed by this PR. Remote access is tested with a mocked TailscaleTransport only.

Verification run locally:

PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests/test_plan_phase3.py -q -> 7 passed
PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests/test_smoke.py -q -> 5 passed
PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests control-plane/platformctl/transport/tests -q -> 325 passed
PYTHONPATH=control-plane python3 -m platformctl.cli validate modules/honcho-redis --strict-v2 --json -> exitCode 0
git diff --check -> clean

Known constraints

docker inspect <container> cannot prove the cataloged repo digest when compose is not digest-pinned. If the tag matches and image_digest_pinned_in_compose: false, the plan records IMAGE_DIGEST_NOT_VERIFIED instead of inventing false digest certainty.

Packet 3.2 requested plan exit code 0=no drift, 1=drift found, 2=error; this PR implements that as a command-local platformctl plan contract while preserving existing platform-wide constants used by apply/validate.

Explicit out-of-scope

No apply changes.
No real SSH to RS2000 during tests.
No production mutation.
No attempt to solve digest proof beyond container inspect.
No changes to canary credentials or Forgejo identity wiring.

Requested decision

Review whether this is a safe Packet 3.2 read-only drift primitive and whether the command-local plan exit-code contract is acceptable for this stack.

Merge blockers

Any real mutation path from plan.
Any reviewer-confirmed false no-drift result for container name/service/running/image tag.
Any secret or credential exposure.
Failing tests.

Spec sources read

prompts/codex-cutover-flight/dispatch.md — cutover flight framing.
prompts/codex-cutover-flight/phase-3-operational.md — Packet 3.2 scope and acceptance criteria.
prompts/03-control.md — older platformctl plan/apply exit-code contract; read because Packet 3.2 conflicts with the existing global constants.
control-plane/platformctl/plan.py — implementation target.
control-plane/platformctl/cli.py — command wiring target.
control-plane/platformctl/transport/tailscale.py — mocked transport contract from PR #158.
control-plane/platformctl/manifest.py — Manifest fields and loading behavior.
control-plane/platformctl/safety.py — safety guard already used by transport/plan.
modules/honcho-redis/module.yaml — concrete v2 module used for fixture-backed expectations.
control-plane/platformctl/tests/test_smoke.py and control-plane/platformctl/tests/test_validate.py — local test patterns.
control-plane/platformctl/transport/tests/test_tailscale.py — mocked transport test style.

Refs #142

Canary status: missing — fire canary 3+3 manually before merge ## Canary Context Pack ### Product story Phase 3 needs a read-only way to compare platform desired state with runtime state before RS2000 cutover work proceeds. This PR gives the operator a bounded drift signal for one module without applying anything to production. ### What changed - `platformctl plan <module>` now fetches remote read-only state through `TailscaleTransport` by running `docker inspect home-platform-<compose-service>-1`. - Plan output compares container name, Docker Compose service label, running state, and image evidence against `module.yaml`. - `--json` emits the plan object; default output is compact human-readable text. - `--out` accepts either an explicit plan file path or an output directory. - Tests cover mocked transport success, drift detection, artifact writing, observation failure, and human output. ### Why it changed This is Packet 3.2 of the cutover flight. It moves `platformctl plan` from skeleton/no observation to a small real read-only inspection primitive, while keeping mutation for later gated packets. ### Files touched - `control-plane/platformctl/plan.py` - `control-plane/platformctl/cli.py` - `control-plane/platformctl/tests/test_plan_phase3.py` ### Relevant context - Tracking issue: #142 - Stack base: PR #158 transport, which is stacked on PR #157 safety. - Master prompt: `prompts/codex-cutover-flight/phase-3-operational.md` Packet 3.2. - Existing CLI/control-plane prompt: `prompts/03-control.md` for the older platform-wide exit-code contract. ### Runtime evidence No production command was executed by this PR. Remote access is tested with a mocked `TailscaleTransport` only. Verification run locally: - `PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests/test_plan_phase3.py -q` -> 7 passed - `PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests/test_smoke.py -q` -> 5 passed - `PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests control-plane/platformctl/transport/tests -q` -> 325 passed - `PYTHONPATH=control-plane python3 -m platformctl.cli validate modules/honcho-redis --strict-v2 --json` -> exitCode 0 - `git diff --check` -> clean ### Known constraints `docker inspect <container>` cannot prove the cataloged repo digest when compose is not digest-pinned. If the tag matches and `image_digest_pinned_in_compose: false`, the plan records `IMAGE_DIGEST_NOT_VERIFIED` instead of inventing false digest certainty. Packet 3.2 requested plan exit code `0=no drift, 1=drift found, 2=error`; this PR implements that as a command-local `platformctl plan` contract while preserving existing platform-wide constants used by `apply`/`validate`. ### Explicit out-of-scope - No `apply` changes. - No real SSH to RS2000 during tests. - No production mutation. - No attempt to solve digest proof beyond container inspect. - No changes to canary credentials or Forgejo identity wiring. ### Requested decision Review whether this is a safe Packet 3.2 read-only drift primitive and whether the command-local plan exit-code contract is acceptable for this stack. ### Merge blockers - Any real mutation path from `plan`. - Any reviewer-confirmed false no-drift result for container name/service/running/image tag. - Any secret or credential exposure. - Failing tests. ## Spec sources read - `prompts/codex-cutover-flight/dispatch.md` — cutover flight framing. - `prompts/codex-cutover-flight/phase-3-operational.md` — Packet 3.2 scope and acceptance criteria. - `prompts/03-control.md` — older platformctl plan/apply exit-code contract; read because Packet 3.2 conflicts with the existing global constants. - `control-plane/platformctl/plan.py` — implementation target. - `control-plane/platformctl/cli.py` — command wiring target. - `control-plane/platformctl/transport/tailscale.py` — mocked transport contract from PR #158. - `control-plane/platformctl/manifest.py` — `Manifest` fields and loading behavior. - `control-plane/platformctl/safety.py` — safety guard already used by transport/plan. - `modules/honcho-redis/module.yaml` — concrete v2 module used for fixture-backed expectations. - `control-plane/platformctl/tests/test_smoke.py` and `control-plane/platformctl/tests/test_validate.py` — local test patterns. - `control-plane/platformctl/transport/tests/test_tailscale.py` — mocked transport test style. Refs #142

codex added 1 commit

2026-05-10 03:43:00 +02:00

feat(platformctl): implement read-only plan drift check

canary-required / collect-diff (pull_request) Successful in 3s

Details

pyfallow / Pyfallow gate (control-plane) (pull_request) Successful in 15s

Details

python-ci / Python 3.11 (pull_request) Successful in 44s

Details

python-ci / Python 3.12 (pull_request) Successful in 42s

Details

python-ci / Python 3.13 (pull_request) Successful in 43s

Details

canary-required / canary (pull_request) Successful in 12s

Details

5481cf194f

codex added the

class/security-sensitive

label

2026-05-10 03:43:15 +02:00

codex commented

2026-05-10 03:50:43 +02:00

Author

Collaborator

Ollama Cloud review for PR #159 (Packet 3.2 plan):

Models:

deepseek-v4-pro:cloud — APPROVE, blockers none
kimi-k2.6:cloud — APPROVE, blockers none
minimax-m2.7:cloud — APPROVE, blockers none

Nonblocking notes consolidated:

drift comparison is intentionally narrow for this packet: container name, compose service label, running state, and image only; ports/env/volumes are follow-up surface, not part of Packet 3.2 acceptance
desired running state is currently assumed true; dormant/stopped-by-design modules need later policy support
missing image_observed produces a warning rather than drift; acceptable for now because there is no manifest image claim to compare, but should be tightened when image policy is made stricter
JSON artifact uses the command-local 0/1/2 plan exit contract; checked apply.py locally and it consumes plan["changes"], not artifact exitCode, so this is not currently a blocker

Verification before review:

PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests/test_plan_phase3.py -q — 7 passed
PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests/test_smoke.py -q — 5 passed
PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests control-plane/platformctl/transport/tests -q — 325 passed
PYTHONPATH=control-plane python3 -m platformctl.cli validate modules/honcho-redis --strict-v2 --json — exitCode 0
git diff --check — clean

Official platform canary remains missing; this comment is the requested external Ollama review checkpoint, not a substitute for the platform canary.

Ollama Cloud review for PR #159 (Packet 3.2 plan): Models: - deepseek-v4-pro:cloud — APPROVE, blockers none - kimi-k2.6:cloud — APPROVE, blockers none - minimax-m2.7:cloud — APPROVE, blockers none Nonblocking notes consolidated: - drift comparison is intentionally narrow for this packet: container name, compose service label, running state, and image only; ports/env/volumes are follow-up surface, not part of Packet 3.2 acceptance - desired running state is currently assumed true; dormant/stopped-by-design modules need later policy support - missing `image_observed` produces a warning rather than drift; acceptable for now because there is no manifest image claim to compare, but should be tightened when image policy is made stricter - JSON artifact uses the command-local 0/1/2 plan exit contract; checked `apply.py` locally and it consumes `plan["changes"]`, not artifact `exitCode`, so this is not currently a blocker Verification before review: - `PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests/test_plan_phase3.py -q` — 7 passed - `PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests/test_smoke.py -q` — 5 passed - `PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests control-plane/platformctl/transport/tests -q` — 325 passed - `PYTHONPATH=control-plane python3 -m platformctl.cli validate modules/honcho-redis --strict-v2 --json` — exitCode 0 - `git diff --check` — clean Official platform canary remains missing; this comment is the requested external Ollama review checkpoint, not a substitute for the platform canary.

codex referenced this pull request

2026-05-10 03:50:52 +02:00

[coordination-lane] Cutover Flight Phase 2: v2 catalog to gate #142