docs: define cicd drift contract

2026-05-21 12:16:36 +00:00
parent a2c469ee8c
commit 92dff00028
2 changed files with 279 additions and 0 deletions
@@ -16,6 +16,43 @@ The standard release shape is:

 `backend-core` and D601 `code-queue` may be validated only in dev in this phase. This document must not be used to introduce production deploy validation for either service.

+## Phase-One Deploy.json Consolidation Contract
+
+Issue #60 moves CI/CD image deployment toward one release-intent source. The implemented `deploy.json` schema still carries only `id`, `repo` and `commitId`; this section defines the phase-one migration contract before changing runtime behavior.
+
+Current duplicated configuration surfaces are:
+
+- Service source and version: `deploy.json.environments.*.services[]`, `config.json.microservices[].repository`, `CI.json.artifacts[].source`, runtime `UNIDESK_DEPLOY_*` metadata and service health payloads.
+- Image repository, tag and digest: `CI.json.artifacts[].image`, artifact-registry consumer specs, Compose/Kubernetes image fields, registry digest probes and docs tables.
+- Runtime target metadata: `config.json` provider/deployment entries, Compose service/container names, k3s namespaces, Kubernetes Deployment/Service names, artifact-registry target specs and runtime manifests.
+- Deployment parameters: runtime env prefixes, required secret keys, health deploy metadata requirements, resource requests/limits, rollout strategy and dev/prod support gates.
+- Consumer scope: `deploy.json` dev/prod service lists, deploy/artifact-registry allowlists, dev/prod Kubernetes manifests and service-specific documentation.
+
+Phase one extends the desired-state model in this order:
+
+1. Keep existing `deploy.json` `id`, `repo` and `commitId` as the deployed source/version authority. All environment-ref deploy commands continue reading `origin/master:deploy.json`.
+2. Add optional deploy-owned artifact identity fields after the static drift guard is green: `artifact.kind`, `artifact.repository`, `artifact.tag`, optional `artifact.digestRef`, and `artifact.upstreamDigestRef` for upstream-image services. For source-build services, `artifact.tag` must equal the selected commit unless a future schema explicitly records a digest-only release.
+3. Add consumer intent fields: `consumer.kind`, `consumer.dev.enabled`, `consumer.prod.enabled`, `consumer.supportLevel`, `consumer.targetRef` and `consumer.noRuntimeSourceBuild`. These describe whether the service is `main-server-compose`, `d601-k3s-managed`, `d601-direct-compose`, `upstream-digest`, `dry-run-only` or `unsupported`; low-level object names still come from config/manifests until renderers exist.
+4. Add deployment-time metadata that must be common across CI, dev CD and prod CD: deploy env prefix, health deploy-metadata requirement, required runtime secret key names, rollback policy, and resource profile identifiers. The planned first keys are `health.deployMetadataRequired` and `runtime.requiredSecretKeys`. Secret values, credentials, volumes and host paths do not move into `deploy.json`.
+5. Teach CI producer dry-run, deploy plan and artifact-registry dry-run to render from `deploy.json` first and compare mirrored `CI.json`/`config.json`/manifest values as derived copies. A mismatch is drift, not an alternate source of truth.
+
+Fields that stay outside `deploy.json` during phase one:
+
+- `CI.json`: producer pipeline name, source root, Dockerfile path and success summary shape. Once artifact identity is in `deploy.json`, `CI.json.artifacts[].image.repository` becomes a compatibility mirror checked for drift.
+- `config.json`: provider id, proxy route and port policy, backend health path, Compose file/service/container names, development SSH/worktree details, and secret source locations.
+- Compose and Kubernetes manifests: concrete container specs, volumes, PVCs, security context, rollout strategy and raw resource requests/limits until a renderer owns those files.
+- Artifact-registry executor code: low-level pull/import/retag/recreate commands, registry probes and platform-specific verification scripts. The executor must consume the normalized deploy plan instead of hardcoding release intent.
+
+The drift contract is:
+
+- `deploy.json` wins for release intent. `config.json.microservices[].repository.commitId` is compatibility data only and must not drive env-ref deploys.
+- `deploy.json.repo` and `CI.json.artifacts[].source.repo` must match for every source-build service that appears in `deploy.json`.
+- Image tags used by CI/CD must be commit-pinned or digest-pinned. Mutable tags such as `latest` are never valid release evidence.
+- Runtime topology may be mirrored in dry-run output, but deployment commands must treat it as derived target metadata and keep `noRuntimeSourceBuild=true` for reviewed artifact consumers.
+- Upstream-image services must stay `blocked` in CI source-build publishing until an upstream digest or mirror digest consumer exists.
+
+Lightweight evidence for this contract is `bun scripts/issue-60-cicd-drift-contract-test.ts`. The test parses local JSON/docs only; it does not publish images, deploy services, restart containers, run Playwright or run full e2e.
+
 ## Artifact Catalog

 Root `CI.json` is the CI producer catalog. It is not a deployment manifest.
@@ -127,6 +164,7 @@ Minimum evidence for this lane is:
 | k3s control bridge dry-run | `bun scripts/cli.ts deploy apply --env prod --service k3sctl-adapter --dry-run` |
 | CI producer preflight | `bun scripts/cli.ts ci publish-user-service --service <service> --commit <full-sha> --dry-run` |
 | Decision Center desired/live no-build drift guard | `bun scripts/decision-center-desired-state-contract-test.ts` |
+| Issue #60 phase-one deploy.json drift guard | `bun scripts/issue-60-cicd-drift-contract-test.ts` |

 ### Upstream Image Evidence