S27 follow-up: track spec drifts for background-jobs foundation Phase 1 plan
Context
During implementation of the background-jobs foundation Phase 1 plan, several spec drifts have been identified between the implementation and the normative spec text (S27, S05). Rather than amending the spec on every plan step MR, we will batch and resolve all drifts in a single spec-reconciliation MR once the implementation steps stabilise.
Related: #95 (formalise spec/plan drift resolution in `/validate-step`).
Known drifts
S27 — Background Jobs Foundation
| Drift | Spec (current) | Implementation | Resolution |
|---|---|---|---|
| `Config.jobs` field number | `4` | `6` | Spec needs update: `4` → `6` |
| `RiverConfig` Phase 2 retention fields carry `min_len = 1` | `completed_job_retention`, `discarded_job_retention`, `cancelled_job_retention` all have `(buf.validate.field).string.min_len = 1` | Constraint dropped so Phase 1 configs validate without populating Phase 2 fields | Spec needs update: remove `min_len = 1` from Phase 2 retention fields |
| `ALTER TYPE ... ADD VALUE` marked NO TRANSACTION | S27 lists `ALTER TYPE ... ADD VALUE` among DDL that cannot run inside a transaction, for which the extractor emits `+goose NO TRANSACTION` | Transaction-safe on PostgreSQL 12+ because the new value is not used in the same migration (matching upstream River, which applies it transactionally); the extractor does NOT emit the directive | Spec needs update: drop `ALTER TYPE ... ADD VALUE` from the NO-TRANSACTION example, or note it is transaction-safe on PG 12+ when the new value is unused in the same migration |
S05 — Distributed State
| Drift | Spec (current) | Implementation | Resolution |
|---|---|---|---|
| `RedisClientOverrides` duration type | `google.protobuf.Duration` | `string` with `time.ParseDuration` at startup (house style, matching every other duration in the proto file) | Spec needs update: `google.protobuf.Duration` → `string` to match house style |
| `Redis CI test topology mechanism` | S05 Testing section prescribes an in-tree `redis-ci` Docker image with a `REDIS_ROLE`-driven entrypoint (`primary`/`replica`/`sentinel`/`cluster-node`/`cluster-starter`) consumed via GitLab CI `services:` | Stock `redis:7-alpine` (local) / apt `redis` (CI) provisioned in-job on `127.0.0.1` via `scripts/ci/redis/setup-{single,sentinel,cluster}.sh` in `before_script`; no custom image, no `services:`, no `build:redis-ci` job | Spec needs update: replace the custom-image/`REDIS_ROLE`/`services:` mechanism with the stock-redis in-job-script approach. The plan's Step 5 `Files` entry is correspondingly stale (tracked here, not amended per-step). |
Acceptance criteria
- S27 spec proto blocks match the shipped implementation
- S05 spec proto blocks match the shipped implementation
- Any prose/YAML examples in the specs are consistent with the updated proto blocks
Edited by Suleimi Ahmed