fix(cutover): import Meerkat compose and gate stateful auto-apply #296

Merged

pdurlej merged 1 commit from codex/269/canonical-compose-import-meerkat into main

2026-05-16 11:20:45 +02:00

codex commented

2026-05-16 09:46:53 +02:00

Collaborator

Canary status: missing - Forgejo checks plus operator merge gate required before merge

Canary Context Pack

Product story

RS2000 canonical compose should describe the services the deploy lane is allowed to reason about. np-meerkat-frontend and matrix-well-known were live/orphaned containers with module manifests, but absent from the canonical compose tree, so auto-apply could only fail late or stay blocked by data gaps.

What changed

Imports matrix-well-known, np-meerkat-backend, and np-meerkat-frontend into compose/apps/compose.yaml from sanitized live/legacy evidence.
Blocks auto-apply v1 for non-stateless modules so the imported Meerkat backend remains visible to compose but cannot enter the F2 no-op lane.
Adds compose/** to release-root promotion so canonical compose changes reach /opt/pdurlej-platform/current before later apply commands depend on them.

Why it changed

PR #295 correctly blocked modules missing from canonical compose. This PR fixes the data gap without weakening the safety boundary: stateless frontend/matrix can become F2 candidates; stateful backend stays F3-gated.

Files touched

.forgejo/workflows/release-root-promote.yml
compose/apps/compose.yaml
control-plane/platformctl/ci/auto_apply_scope.py
control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py
docs/ci/runner-contract.md
runbooks/forgejo-actions-runner.md
tests/test_release_root_promote.py

Relevant context

#269: Meerkat canonical compose data gap
#142: RS2000 cutover lane
#279/#293/#294: release-root promotion lane
ADR-0018: agentic-first root-cause fixes

Runtime evidence

Read-only evidence gathered before the PR:

live containers exist: home-platform-matrix-well-known-1, home-platform-np-meerkat-backend-1, home-platform-np-meerkat-frontend-1
Meerkat env evidence used variable names only, not values: MEERKAT_BACKEND_IMAGE, MEERKAT_FRONTEND_IMAGE, MEERKAT_HOSTNAME, MEERKAT_JWT_SECRET_KEY
remote read-only compose config from this branch passed on RS2000 using /opt/pdurlej-platform/runtime/compose.env
composed services include matrix-well-known, np-meerkat-backend, np-meerkat-frontend

Known existing warning during config check: MiroTalk Admin variables are not set in runtime env. That warning predates this PR and does not block compose validation.

Known constraints

This PR does not run docker compose up, platformctl apply, or restart production containers.
np-meerkat-backend is stateful and must not be smoked in F2.
np-meerkat-frontend depends on the backend, so future smoke should remain no-op first and stop on red.

Explicit out-of-scope

No Meerkat backend F3 smoke.
No orphan container cleanup.
No route/auth redesign for Meerkat or Matrix.
No secret migration.

Requested decision

Approve merge if checks are green. After merge, release-root should promote because this PR changes the release-root workflow path set and compose/**.

Merge blockers

Compose config does not validate with production env.
Auto-apply allows a stateful module.
Release-root promotion path does not include compose/**.

Spec sources read

compose/apps/compose.yaml - canonical apps compose target
modules/np-meerkat-frontend/module.yaml - stateless frontend manifest
modules/np-meerkat-backend/module.yaml - stateful backend manifest
modules/matrix-well-known/module.yaml - stateless Matrix manifest
control-plane/platformctl/ci/auto_apply_scope.py - auto-apply scope guard
.forgejo/workflows/release-root-promote.yml - release-root promotion trigger
docs/ci/runner-contract.md and runbooks/forgejo-actions-runner.md - deploy/release-root contract docs

Verification

pytest -q control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py tests/test_release_root_promote.py tests/test_deploy_runner_watchdog.py tests/test_deploy_runner_scope_doctor.py -> 40 passed
python control-plane/platformctl/ci/lint_workflows.py --workflows .forgejo/workflows -> 0 findings
auto_apply_scope.py --module matrix-well-known -> eligible
auto_apply_scope.py --module np-meerkat-frontend -> eligible
auto_apply_scope.py --module np-meerkat-backend --fail-on-blocked -> blocked, rc=4, statefulness gate
RS2000 read-only docker compose --env-file /opt/pdurlej-platform/runtime/compose.env -f <branch>/compose/apps/compose.yaml config --quiet -> passed

Closes #269

Canary status: missing - Forgejo checks plus operator merge gate required before merge ## Canary Context Pack ### Product story RS2000 canonical compose should describe the services the deploy lane is allowed to reason about. `np-meerkat-frontend` and `matrix-well-known` were live/orphaned containers with module manifests, but absent from the canonical compose tree, so auto-apply could only fail late or stay blocked by data gaps. ### What changed - Imports `matrix-well-known`, `np-meerkat-backend`, and `np-meerkat-frontend` into `compose/apps/compose.yaml` from sanitized live/legacy evidence. - Blocks auto-apply v1 for non-`stateless` modules so the imported Meerkat backend remains visible to compose but cannot enter the F2 no-op lane. - Adds `compose/**` to release-root promotion so canonical compose changes reach `/opt/pdurlej-platform/current` before later apply commands depend on them. ### Why it changed PR #295 correctly blocked modules missing from canonical compose. This PR fixes the data gap without weakening the safety boundary: stateless frontend/matrix can become F2 candidates; stateful backend stays F3-gated. ### Files touched - `.forgejo/workflows/release-root-promote.yml` - `compose/apps/compose.yaml` - `control-plane/platformctl/ci/auto_apply_scope.py` - `control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py` - `docs/ci/runner-contract.md` - `runbooks/forgejo-actions-runner.md` - `tests/test_release_root_promote.py` ### Relevant context - #269: Meerkat canonical compose data gap - #142: RS2000 cutover lane - #279/#293/#294: release-root promotion lane - ADR-0018: agentic-first root-cause fixes ### Runtime evidence Read-only evidence gathered before the PR: - live containers exist: `home-platform-matrix-well-known-1`, `home-platform-np-meerkat-backend-1`, `home-platform-np-meerkat-frontend-1` - Meerkat env evidence used variable names only, not values: `MEERKAT_BACKEND_IMAGE`, `MEERKAT_FRONTEND_IMAGE`, `MEERKAT_HOSTNAME`, `MEERKAT_JWT_SECRET_KEY` - remote read-only compose config from this branch passed on RS2000 using `/opt/pdurlej-platform/runtime/compose.env` - composed services include `matrix-well-known`, `np-meerkat-backend`, `np-meerkat-frontend` Known existing warning during config check: MiroTalk Admin variables are not set in runtime env. That warning predates this PR and does not block compose validation. ### Known constraints - This PR does not run `docker compose up`, `platformctl apply`, or restart production containers. - `np-meerkat-backend` is stateful and must not be smoked in F2. - `np-meerkat-frontend` depends on the backend, so future smoke should remain no-op first and stop on red. ### Explicit out-of-scope - No Meerkat backend F3 smoke. - No orphan container cleanup. - No route/auth redesign for Meerkat or Matrix. - No secret migration. ### Requested decision Approve merge if checks are green. After merge, release-root should promote because this PR changes the release-root workflow path set and `compose/**`. ### Merge blockers - Compose config does not validate with production env. - Auto-apply allows a stateful module. - Release-root promotion path does not include `compose/**`. ## Spec sources read - `compose/apps/compose.yaml` - canonical apps compose target - `modules/np-meerkat-frontend/module.yaml` - stateless frontend manifest - `modules/np-meerkat-backend/module.yaml` - stateful backend manifest - `modules/matrix-well-known/module.yaml` - stateless Matrix manifest - `control-plane/platformctl/ci/auto_apply_scope.py` - auto-apply scope guard - `.forgejo/workflows/release-root-promote.yml` - release-root promotion trigger - `docs/ci/runner-contract.md` and `runbooks/forgejo-actions-runner.md` - deploy/release-root contract docs ## Verification - `pytest -q control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py tests/test_release_root_promote.py tests/test_deploy_runner_watchdog.py tests/test_deploy_runner_scope_doctor.py` -> 40 passed - `python control-plane/platformctl/ci/lint_workflows.py --workflows .forgejo/workflows` -> 0 findings - `auto_apply_scope.py --module matrix-well-known` -> eligible - `auto_apply_scope.py --module np-meerkat-frontend` -> eligible - `auto_apply_scope.py --module np-meerkat-backend --fail-on-blocked` -> blocked, rc=4, statefulness gate - RS2000 read-only `docker compose --env-file /opt/pdurlej-platform/runtime/compose.env -f <branch>/compose/apps/compose.yaml config --quiet` -> passed Closes #269

codex added 1 commit

2026-05-16 09:46:53 +02:00

fix(cutover): import Meerkat compose and gate stateful auto-apply

infra-docs-drift / docs-drift (pull_request) Successful in 4s

Details

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

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 4s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 19s

Details

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