pdurlej/platform

Fork 0

chore(w8.0): fill source/artifact metadata for stateful candidate set #505

New issue

Closed

opened 2026-05-26 17:54:21 +02:00 by codex · 0 comments

codex commented

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

Collaborator

Spec sources (whitelist)

state/cycle/W8-module-upgrade-prep.md §Current Readiness Snapshot / Wave Plan / Required Evidence Per Upgrade PR
state/cycle/W8-readiness-2026-05-26.md §Readiness Snapshot / Candidate Classification
decisions/0022-module-source-and-release-boundaries.md §Metadata direction / Pilot rollout / Anti-patterns
modules/minio/module.yaml
modules/redis/module.yaml
modules/postgres/module.yaml

Extracted context

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

W8 can start only as a staged pilot program. Broad upgrades are
still blocked by metadata coverage and restore evidence.

From state/cycle/W8-readiness-2026-05-26.md:

Total modules: 88
Modules with `spec.source`: 6
Modules with `spec.artifact`: 6
Missing source metadata: 82
Missing artifact metadata: 82

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

Desired state says what the platform intends to run. Observed state records
what production actually ran at audit time. Agents must not have to infer one
from the other.

From modules/minio/module.yaml, modules/redis/module.yaml, modules/postgres/module.yaml:

Each module has `spec.runtime.image_observed`, but lacks explicit
`spec.source` and `spec.artifact` metadata.

Do NOT read (unless escape hatch fires)

compose/ — this is metadata-only; compose/env changes are out of scope.
config/ — no runtime config changes.
state/cutover/ — cleanup/restore work is adjacent but not part of this metadata batch.
Live RS2000 paths — no runtime inspection is required for this PR.

Allowed touched paths

modules/minio/module.yaml (modify)
modules/redis/module.yaml (modify)
modules/postgres/module.yaml (modify)
Optional: state/cycle/W8-module-upgrade-prep.md (modify, only if adding a short metadata-batch note)

Why this exists (product-first)

W8 cannot safely upgrade stateful modules while agents have to infer source and artifact intent from observed runtime strings. This batch makes the next stateful upgrade planning boring: each module declares where its image comes from, what artifact should be tracked, and why updates remain manual.

Why this matters now

W8.0 and W8.1 proved the packet shape, but broad upgrades remain blocked by sparse metadata. minio, redis, and postgres are core/stateful enough that they should have explicit metadata before any W8.3 or W8.final work tries to reason about them.

What "done" looks like

minio, redis, and postgres each have spec.source and spec.artifact matching their observed image family/tag.
Each update policy is conservative (manual unless the PR gives a defensible reason otherwise).
No compose, env, secret, runtime, backup, or live host file changes.
PYTHONPATH=control-plane python3 -m platformctl.cli validate all --json exits with zero failures.
PR body states this is metadata-only and requests no runtime apply/recreate.

Scope

In scope:

Add source/artifact metadata for the named stateful candidate set only.
Keep observed runtime metadata separate from desired artifact metadata.

Out of scope:

Image upgrades.
Runtime apply/recreate/restart.
Backup/restore execution.
Adding source/artifact metadata for all 82 missing modules.

Suggested approach

For each module, derive source/artifact from the existing spec.runtime.image_observed image family/tag.
Use ADR-0022 vocabulary: upstream-image, upstream-tag, oci-image, upstream-registry.
Keep update policy manual for these stateful/core modules.
Run platform validation.

Escape hatch

If an observed image cannot be cleanly mapped to source/artifact metadata, stop and comment on #389 with the gap. Do not invent metadata to satisfy the checklist.

Unknowns / owner questions

None expected for a metadata-only conservative batch.

Risk class

risk/runtime — metadata affects future upgrade decisions for stateful modules
risk/process — agents use this metadata for W8 routing
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, #501, #502, #503, #504

## Spec sources (whitelist) - `state/cycle/W8-module-upgrade-prep.md` §Current Readiness Snapshot / Wave Plan / Required Evidence Per Upgrade PR - `state/cycle/W8-readiness-2026-05-26.md` §Readiness Snapshot / Candidate Classification - `decisions/0022-module-source-and-release-boundaries.md` §Metadata direction / Pilot rollout / Anti-patterns - `modules/minio/module.yaml` - `modules/redis/module.yaml` - `modules/postgres/module.yaml` ## Extracted context > From `state/cycle/W8-module-upgrade-prep.md`: > ``` > W8 can start only as a staged pilot program. Broad upgrades are > still blocked by metadata coverage and restore evidence. > ``` > > From `state/cycle/W8-readiness-2026-05-26.md`: > ``` > Total modules: 88 > Modules with `spec.source`: 6 > Modules with `spec.artifact`: 6 > Missing source metadata: 82 > Missing artifact metadata: 82 > ``` > > From `decisions/0022-module-source-and-release-boundaries.md`: > ``` > Desired state says what the platform intends to run. Observed state records > what production actually ran at audit time. Agents must not have to infer one > from the other. > ``` > > From `modules/minio/module.yaml`, `modules/redis/module.yaml`, `modules/postgres/module.yaml`: > ``` > Each module has `spec.runtime.image_observed`, but lacks explicit > `spec.source` and `spec.artifact` metadata. > ``` ## Do NOT read (unless escape hatch fires) - `compose/` — this is metadata-only; compose/env changes are out of scope. - `config/` — no runtime config changes. - `state/cutover/` — cleanup/restore work is adjacent but not part of this metadata batch. - Live RS2000 paths — no runtime inspection is required for this PR. ## Allowed touched paths - `modules/minio/module.yaml` (modify) - `modules/redis/module.yaml` (modify) - `modules/postgres/module.yaml` (modify) - Optional: `state/cycle/W8-module-upgrade-prep.md` (modify, only if adding a short metadata-batch note) ## Why this exists (product-first) W8 cannot safely upgrade stateful modules while agents have to infer source and artifact intent from observed runtime strings. This batch makes the next stateful upgrade planning boring: each module declares where its image comes from, what artifact should be tracked, and why updates remain manual. ## Why this matters now W8.0 and W8.1 proved the packet shape, but broad upgrades remain blocked by sparse metadata. `minio`, `redis`, and `postgres` are core/stateful enough that they should have explicit metadata before any W8.3 or W8.final work tries to reason about them. ## What "done" looks like - [ ] `minio`, `redis`, and `postgres` each have `spec.source` and `spec.artifact` matching their observed image family/tag. - [ ] Each update policy is conservative (`manual` unless the PR gives a defensible reason otherwise). - [ ] No compose, env, secret, runtime, backup, or live host file changes. - [ ] `PYTHONPATH=control-plane python3 -m platformctl.cli validate all --json` exits with zero failures. - [ ] PR body states this is metadata-only and requests no runtime apply/recreate. ## Scope **In scope:** - Add source/artifact metadata for the named stateful candidate set only. - Keep observed runtime metadata separate from desired artifact metadata. **Out of scope:** - Image upgrades. - Runtime apply/recreate/restart. - Backup/restore execution. - Adding source/artifact metadata for all 82 missing modules. ## Suggested approach 1. For each module, derive source/artifact from the existing `spec.runtime.image_observed` image family/tag. 2. Use ADR-0022 vocabulary: `upstream-image`, `upstream-tag`, `oci-image`, `upstream-registry`. 3. Keep update policy manual for these stateful/core modules. 4. Run platform validation. ## Escape hatch If an observed image cannot be cleanly mapped to source/artifact metadata, stop and comment on #389 with the gap. Do not invent metadata to satisfy the checklist. ## Unknowns / owner questions - None expected for a metadata-only conservative batch. ## Risk class - [x] `risk/runtime` — metadata affects future upgrade decisions for stateful modules - [x] `risk/process` — agents use this metadata for W8 routing - [ ] `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, #501, #502, #503, #504

codex added this to the 09 - Module upgrade waves milestone

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

codex added the

labels

2026-05-26 17:54:21 +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