pdurlej/platform

Fork 0

docs(w8.3): define stateful and sidecar upgrade gate #507

New issue

Closed

opened 2026-05-26 17:54:22 +02:00 by codex · 1 comment

codex commented

2026-05-26 17:54:22 +02:00

Collaborator

Spec sources (whitelist)

state/cycle/W8-module-upgrade-prep.md §W8.3 sidecar/stateful / Required Evidence Per Upgrade PR / Stop Conditions
state/cycle/W8-readiness-2026-05-26.md §Candidate Classification / Stop Conditions
state/cycle/W8-minio-init-pilot.md §Risk Class / Smoke Contract For Future Runtime Approval
decisions/0022-module-source-and-release-boundaries.md §Update workflow / Anti-patterns

Extracted context

From state/cycle/W8-module-upgrade-prep.md:

W8.3 sidecar/stateful: Upgrade stateful or sidecar-bound services.
Gate: Backup-before plus restore/rollback path.

From state/cycle/W8-minio-init-pilot.md:

Runtime execution of a future tag change still requires operator approval and
should treat `minio` as the backup reference module.

From decisions/0022-module-source-and-release-boundaries.md:

Stateful, public-edge, auth, and security-sensitive modules stay manually
gated until explicit policy says otherwise.

Do NOT read (unless escape hatch fires)

Live RS2000 paths — this is a gate definition, not a smoke.
compose/ — no service wiring changes.
state/cutover/ — destructive cleanup is a separate M01/W3d gate.

Allowed touched paths

state/cycle/W8-stateful-sidecar-gate.md (create)
state/cycle/W8-module-upgrade-prep.md (modify, short gate reference only)

Why this exists (product-first)

W8 will slow down or become risky if every stateful module has to re-argue the same backup/rollback rules. A small gate document lets agents prepare upgrade PRs consistently while keeping real state changes behind the right operator approvals.

Why this matters now

minio-init proved a sidecar-bound packet. Before any minio, redis, postgres, or similar module upgrade, the platform needs one shared checklist for backup-before, restore confidence, smoke shape, and stop conditions.

What "done" looks like

A W8.3 gate document defines required evidence for stateful, sidecar-bound, secret-bearing, and public-edge upgrade classes.
The gate explicitly distinguishes repo-only packet PRs from runtime apply/recreate approvals.
The gate says when #433 W3d/full sandbox DR is mandatory before continuing.
The gate includes at least one example each for minio-init, minio, redis, and postgres using metadata-only language.
No module image/tag/digest changes and no runtime instructions that imply immediate execution.

Scope

In scope:

Gate/checklist documentation for W8.3.
References back to #389/#501/#502.

Out of scope:

Executing upgrades.
Creating backups.
Running restore drills.
Editing module manifests beyond a pointer, unless separately justified.

Suggested approach

Start from the W8 prep evidence list.
Convert it into class-specific gates.
Make all runtime mutation language explicitly operator-gated.
Add a short pointer in W8 prep.

Escape hatch

If the gate needs a new ADR or contradicts ADR-0022/W3 restore stance, stop and comment on #389 rather than inventing policy.

Unknowns / owner questions

Whether to require #433 before every W8.3 runtime apply or only before broad/core batches. If unclear, default to stricter/manual wording.

Risk class

risk/runtime
risk/process
risk/exposure
risk/product

Class of service

class/security-sensitive

Trace

Original source: #389 W8 coordination lane after #501/#502
Migrated by: codex, 2026-05-26
Related issues / PRs: #389, #433, #501, #502, #503, #504

## Spec sources (whitelist) - `state/cycle/W8-module-upgrade-prep.md` §W8.3 sidecar/stateful / Required Evidence Per Upgrade PR / Stop Conditions - `state/cycle/W8-readiness-2026-05-26.md` §Candidate Classification / Stop Conditions - `state/cycle/W8-minio-init-pilot.md` §Risk Class / Smoke Contract For Future Runtime Approval - `decisions/0022-module-source-and-release-boundaries.md` §Update workflow / Anti-patterns ## Extracted context > From `state/cycle/W8-module-upgrade-prep.md`: > ``` > W8.3 sidecar/stateful: Upgrade stateful or sidecar-bound services. > Gate: Backup-before plus restore/rollback path. > ``` > > From `state/cycle/W8-minio-init-pilot.md`: > ``` > Runtime execution of a future tag change still requires operator approval and > should treat `minio` as the backup reference module. > ``` > > From `decisions/0022-module-source-and-release-boundaries.md`: > ``` > Stateful, public-edge, auth, and security-sensitive modules stay manually > gated until explicit policy says otherwise. > ``` ## Do NOT read (unless escape hatch fires) - Live RS2000 paths — this is a gate definition, not a smoke. - `compose/` — no service wiring changes. - `state/cutover/` — destructive cleanup is a separate M01/W3d gate. ## Allowed touched paths - `state/cycle/W8-stateful-sidecar-gate.md` (create) - `state/cycle/W8-module-upgrade-prep.md` (modify, short gate reference only) ## Why this exists (product-first) W8 will slow down or become risky if every stateful module has to re-argue the same backup/rollback rules. A small gate document lets agents prepare upgrade PRs consistently while keeping real state changes behind the right operator approvals. ## Why this matters now `minio-init` proved a sidecar-bound packet. Before any `minio`, `redis`, `postgres`, or similar module upgrade, the platform needs one shared checklist for backup-before, restore confidence, smoke shape, and stop conditions. ## What "done" looks like - [ ] A W8.3 gate document defines required evidence for `stateful`, `sidecar-bound`, `secret-bearing`, and `public-edge` upgrade classes. - [ ] The gate explicitly distinguishes repo-only packet PRs from runtime apply/recreate approvals. - [ ] The gate says when #433 W3d/full sandbox DR is mandatory before continuing. - [ ] The gate includes at least one example each for `minio-init`, `minio`, `redis`, and `postgres` using metadata-only language. - [ ] No module image/tag/digest changes and no runtime instructions that imply immediate execution. ## Scope **In scope:** - Gate/checklist documentation for W8.3. - References back to #389/#501/#502. **Out of scope:** - Executing upgrades. - Creating backups. - Running restore drills. - Editing module manifests beyond a pointer, unless separately justified. ## Suggested approach 1. Start from the W8 prep evidence list. 2. Convert it into class-specific gates. 3. Make all runtime mutation language explicitly operator-gated. 4. Add a short pointer in W8 prep. ## Escape hatch If the gate needs a new ADR or contradicts ADR-0022/W3 restore stance, stop and comment on #389 rather than inventing policy. ## Unknowns / owner questions - Whether to require #433 before every W8.3 runtime apply or only before broad/core batches. If unclear, default to stricter/manual wording. ## Risk class - [x] `risk/runtime` - [x] `risk/process` - [ ] `risk/exposure` - [ ] `risk/product` ## Class of service - [ ] `class/security-sensitive` ## Trace - Original source: #389 W8 coordination lane after #501/#502 - Migrated by: codex, 2026-05-26 - Related issues / PRs: #389, #433, #501, #502, #503, #504

codex added this to the 09 - Module upgrade waves milestone

2026-05-26 17:54:22 +02:00

codex added the

labels

2026-05-26 17:54:22 +02:00

codex referenced this issue

2026-05-26 17:55:28 +02:00

meta(upgrades): plan staged module upgrade waves after metadata and DR #389

codex commented

2026-05-26 20:11:37 +02:00

Author

Collaborator

Sequencing note from codex: keep this proposed until #505/#506 land; then mark ready-for-agent as the next W8 batch. This is not blocked on more ADR/policy work, only on avoiding parallel drift while the first two packets establish current evidence.

codex referenced this issue from a pull request that will close it,

2026-05-26 22:29:50 +02:00

docs(w8): define stateful sidecar upgrade gate #511