feat: closed-schema transition chain + guard link 0001 (IDEA-245, ISS-9) #346

Merged
janpeter merged 7 commits from feat/idea-245-closed-schema-chain into main 2026-10-09 16:30:39 +02:00
Owner

IDEA-245 / ISS-9 — PR 1 (Scrum4Me). Sprint S-2026-10-09-I245, PBI-194, ST-1651, T1–T5.

What

An append-only closed-schema transition chain: after the IDEA-213 adoption and IDEA-227, adopted functions (definition only) and table triggers can change through links (scripts/db-access/transitions/closed-schema/NNNN-*.json + prisma/migrations/<ts>_closed_schema_<NNNN>_*/migration.sql). Manifest, receipt and the IDEA-227 files stay byte-equal.

  • T1 lib/db-access/closed-schema-transitions.ts: chain validator (sequence, previous, manifest pin, migration-id rules, derived before-schema, function/trigger change rules, NOOP outside s4m_dispatch_test) and SQL lint (BEGIN/COMMIT shape, dollar-quote aware, targets == keys).
  • T2 expectedSchemaHashes (ledger prefix after IDEA-227, ORDER, checksum, HISTORY_MISSING also without chain) used by verifyAdoptionAfter (optional 6th param chain), requireAdoption and the activation preflight; lib/db-access/adoption-context.ts (loadAdoptionContext) as the one loader; CLI keeps its receipt order. Both modules are literal bundle entries.
  • T3 migrate.ts, closed-schema-replay.ts (per-link before/after verification, capture file), baseline filter, provision --stage adoption|chain, test:dispatch:chain, CI: both Postgres services pinned to the prod RepoDigest and a second provision/test step pair in the queue-dispatch job.
  • T4 link 0001 20261009140000_closed_schema_0001_task_guard_unscoped_stops: queue_dispatch_guard_task() also releases a task binding after a claim_bound_unscoped (artefact) or signed_off_unstarted (signed-off incarnation) stop of an attempt without scope/start/started_scope. afterSchema captured by replay on the pinned image.
  • T5 runbooks db-access-policy.md (chain, operator snippet, capture/NOOP, rollout, mismatch, no old-bundle rollback) and queue-dispatch.md (guard extension, follow-ups).

Evidence

  • scrum4me-mcp facts (T0): GRILLS/idea-245-t0-mcp-evidence rev 2, pin 48555ea6 (stop-evidence.ts:58 'claim_bound_unscoped', :106 'signed_off_unstarted', started_scope payload attempt_id).
  • Prod Postgres (measured read-only on 154, 2026-10-09): postgres@sha256:347bc4e64006d47bb255b0e28652d08590260a5e97f6b55f6ba1c0b31aef58b3, linux/amd64, 17.9 (Debian 17.9-1.pgdg13+1). CI runners are x86_64. CI pin: postgres:17.9@sha256:347bc4e6…58b3.
  • Local recipe on that digest: provision → test:dispatch 17 files/49 tests; provision --stage chain (server_version 17.9) → test:dispatch:chain 5 files/26 tests. Sanity: the new guard tests against the old guard fail exactly on the two release cases.
  • npm run verify green (403 files / 4242 tests); docs:check-links green; npm run build compiles (page-data collection needs the real env → CI).
  • git diff --exit-code 6e0d6acc -- lib/db-access/api-token-usage-transition.ts scripts/db-access/transitions/idea-227-token-usage.json and git diff --exit-code --diff-filter=MDRT 6e0d6acc -- __tests__/queue-dispatch/ clean.
  • CI run id: see below (added once green).

Rollout (T6 — JP, every step a separate authorisation)

  1. Prod digest/arch/server_version equal to the green CI run for exactly the merged commit; ops-agent precheck/preflight callers go through loadAdoptionContext (a chainless caller gets HISTORY_MISSING after step 3).
  2. Merge; first deploy stops with exit 3 on the new bundle hash (POLICY_HASH changes).
  3. Approve Policy Hash → wrapper precheck + activation preflight green (link present, not applied).
  4. prisma-operator.sh deploy → green.
  5. Activation preflight → green.

Then PR 2 (scrum4me-mcp, T7): remove closesAtStop.

Spec: SPECS/idea-245-closed-schema-transitions rev 5 + SPECS/idea-245-spec-delta-capture rev 2; plan: PLANS/idea-245-plan rev 3 + addendum r3.

🤖 Generated with Claude Code

IDEA-245 / ISS-9 — PR 1 (Scrum4Me). Sprint S-2026-10-09-I245, PBI-194, ST-1651, T1–T5. ## What An append-only **closed-schema transition chain**: after the IDEA-213 adoption and IDEA-227, adopted functions (definition only) and table triggers can change through links (`scripts/db-access/transitions/closed-schema/NNNN-*.json` + `prisma/migrations/<ts>_closed_schema_<NNNN>_*/migration.sql`). Manifest, receipt and the IDEA-227 files stay byte-equal. - **T1** `lib/db-access/closed-schema-transitions.ts`: chain validator (sequence, `previous`, manifest pin, migration-id rules, derived before-schema, function/trigger change rules, `NOOP` outside `s4m_dispatch_test`) and SQL lint (BEGIN/COMMIT shape, dollar-quote aware, targets == keys). - **T2** `expectedSchemaHashes` (ledger prefix after IDEA-227, `ORDER`, checksum, `HISTORY_MISSING` also without chain) used by `verifyAdoptionAfter` (optional 6th param `chain`), `requireAdoption` and the activation preflight; `lib/db-access/adoption-context.ts` (`loadAdoptionContext`) as the one loader; CLI keeps its receipt order. Both modules are literal bundle entries. - **T3** `migrate.ts`, `closed-schema-replay.ts` (per-link before/after verification, capture file), baseline filter, `provision --stage adoption|chain`, `test:dispatch:chain`, CI: both Postgres services pinned to the prod RepoDigest and a second provision/test step pair in the `queue-dispatch` job. - **T4** link **0001** `20261009140000_closed_schema_0001_task_guard_unscoped_stops`: `queue_dispatch_guard_task()` also releases a task binding after a `claim_bound_unscoped` (artefact) or `signed_off_unstarted` (signed-off incarnation) stop of an attempt without scope/start/`started_scope`. `afterSchema` captured by replay on the pinned image. - **T5** runbooks `db-access-policy.md` (chain, operator snippet, capture/NOOP, rollout, mismatch, no old-bundle rollback) and `queue-dispatch.md` (guard extension, follow-ups). ## Evidence - scrum4me-mcp facts (T0): `GRILLS/idea-245-t0-mcp-evidence` rev 2, pin `48555ea6` (`stop-evidence.ts:58` `'claim_bound_unscoped'`, `:106` `'signed_off_unstarted'`, `started_scope` payload `attempt_id`). - Prod Postgres (measured read-only on 154, 2026-10-09): `postgres@sha256:347bc4e64006d47bb255b0e28652d08590260a5e97f6b55f6ba1c0b31aef58b3`, linux/amd64, 17.9 (Debian 17.9-1.pgdg13+1). CI runners are x86_64. CI pin: `postgres:17.9@sha256:347bc4e6…58b3`. - Local recipe on that digest: `provision` → `test:dispatch` 17 files/49 tests; `provision --stage chain` (server_version 17.9) → `test:dispatch:chain` 5 files/26 tests. Sanity: the new guard tests against the old guard fail exactly on the two release cases. - `npm run verify` green (403 files / 4242 tests); `docs:check-links` green; `npm run build` compiles (page-data collection needs the real env → CI). - `git diff --exit-code 6e0d6acc -- lib/db-access/api-token-usage-transition.ts scripts/db-access/transitions/idea-227-token-usage.json` and `git diff --exit-code --diff-filter=MDRT 6e0d6acc -- __tests__/queue-dispatch/` clean. - CI run id: see below (added once green). ## Rollout (T6 — JP, every step a separate authorisation) 0. Prod digest/arch/`server_version` equal to the green CI run for **exactly the merged commit**; ops-agent precheck/preflight callers go through `loadAdoptionContext` (a chainless caller gets `HISTORY_MISSING` after step 3). 1. Merge; first deploy stops with exit 3 on the new bundle hash (`POLICY_HASH` changes). 2. Approve Policy Hash → wrapper precheck + activation preflight green (link present, not applied). 3. `prisma-operator.sh deploy` → green. 4. Activation preflight → green. Then PR 2 (scrum4me-mcp, T7): remove `closesAtStop`. Spec: `SPECS/idea-245-closed-schema-transitions` rev 5 + `SPECS/idea-245-spec-delta-capture` rev 2; plan: `PLANS/idea-245-plan` rev 3 + addendum r3. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
prepareClosedSchemaChain validates the append-only chain of closed-schema
links against the original IDEA-213 manifest and the IDEA-227 transition:
sequence, previous, migration-id rules, derived before-schema, the
function/trigger change rules and NOOP outside the s4m_dispatch_test
rebinding. lintClosedSchemaSql enforces the BEGIN/COMMIT shape with
dollar-quote aware tokenizing and target==keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
expectedSchemaHashes derives the expected schema of every closed object
from the ledger: manifest pins, IDEA-227 when applied, then every applied
closed-schema link as a prefix after IDEA-227; a closed-schema ledger row
without descriptor is HISTORY_MISSING, also without a chain.
verifyAdoptionAfter (optional sixth chain parameter), requireAdoption and
the activation preflight use it. loadAdoptionContext reads manifest,
IDEA-227 and the bundled chain; the CLI keeps its receipt order and only
then requires the receipt for a non-empty chain. Both new modules are
literal bundle entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
migrate() moves to its own module. The baseline leaves closed-schema
links out. replayClosedSchemaChain runs each link as the migrator and
verifies before and after (REPLAY_BEFORE/AFTER_MISMATCH), writing the
measured schema to DISPATCH_TEST_CAPTURE_FILE on a mismatch.
provision --stage chain adds IDEA-227, the additive contracts and the
replay, then applies and verifies with receipt and chain and logs
server_version. CI pins both Postgres services to the prod RepoDigest
(postgres 17.9, linux/amd64) and runs a second provision/test pair.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
queue_dispatch_guard_task() is identical to 20260915180000 except the
per-attempt stop evidence inside the existing NOT EXISTS over all
attempts: (A) a claim_bound_unscoped artefact, (B) a signed_off_unstarted
stop of a signed-off incarnation; both only for an attempt without
scope_id, started_at or started_scope event. The descriptor's afterSchema
was captured by replay on postgres 17.9 (the pinned prod digest).
Tests: the guard cases, chain verification, the production intermediate
state before the link runs, and the bundle cases with 0001.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs(runbooks): closed-schema chain, operator snippet, rollout and guard extension (IDEA-245 T5)
All checks were successful
CI / DB Access Policy Gate (pull_request) Successful in 2m2s
CI / Queue Dispatch Guard Gate (pull_request) Successful in 2m39s
CI / Lint, Typecheck, Test & Build (pull_request) Successful in 5m1s
CI / Deploy Manual (workflow_dispatch) (pull_request) Has been skipped
CI / DB Access Production Sentinel (pull_request) Successful in 1m46s
CI / Detect deploy-relevant changes (pull_request) Has been skipped
CI / Deploy Preview (PR) (pull_request) Has been skipped
CI / Deploy Production (main) (pull_request) Has been skipped
f89bd976f4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Author
Owner

CI run 965 green on head f89bd976 (all 8 jobs). Queue Dispatch Guard Gate: stage adoption provision + tests, then stage chain provision (DISPATCH_TEST_SERVER_VERSION 17.9 (Debian 17.9-1.pgdg13+1), closed-schema chain replayed) + chain tests green, on postgres:17.9@sha256:347bc4e6…58b3 (linux/amd64 runner), equal to prod (measured read-only on 154). Rollout step 0 holds for exactly this commit.

🤖 Generated with Claude Code

CI run **965** green on head `f89bd976` (all 8 jobs). Queue Dispatch Guard Gate: stage `adoption` provision + tests, then stage `chain` provision (`DISPATCH_TEST_SERVER_VERSION 17.9 (Debian 17.9-1.pgdg13+1)`, closed-schema chain replayed) + chain tests green, on `postgres:17.9@sha256:347bc4e6…58b3` (linux/amd64 runner), equal to prod (measured read-only on 154). Rollout step 0 holds for exactly this commit. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
s4m-codex-reviewer left a comment

APPROVED

Geen blokkerende bevindingen in de diff van f89bd976f426f2667177079da81978e6f044813d.

Findings

  • MINOR — docs/runbooks/db-access-policy.md:521 — Vervang postgres -V door SHOW server_version via de verbinding met scrum4me-postgres. De binaryversie (mogelijk op de host) bewijst niet de versie van de draaiende server; de bindende spec en het plan vereisen die vergelijking met de CI-replay.

Plan en productstandaarden

Plan gekoppeld via pbi (Scrum4Me): IDEA-245 uitvoeringsplan rev 3. Ook getoetst aan de gekoppelde spec rev 5, spec-delta capture rev 2 en het in de PR genoemde plan-addendum r3. Geen references- of omitted-velden aangeleverd.

De PR rondt T1–T5 af: ketenvalidatie, bundle-loader, ledgercontrole, beide provisioning-stages, guard-schakel 0001 en runbooks zijn aanwezig en sluiten aan op het plan. De beschermde IDEA-227-bestanden en bestaande dispatch-testbestanden zijn byte-ongewijzigd tegenover 6e0d6acc. T6 (productie-uitrol) en T7 (scrum4me-mcp-vervolg) zijn expliciete vervolgstappen, geen ontbrekend werk binnen deze PR. Geen blokkerende afwijkingen in architectuur, patronen, tests of documentatie gevonden.

Verificatie

  • PR en head-SHA via Forgejo bevestigd.
  • Forgejo CI-run 965, op deze head: Lint, Typecheck, Test & Build, DB Access Policy Gate en Queue Dispatch Guard Gate groen.
  • Lokaal: 39 gerichte tests groen; typecheck groen met 8 GiB Node-heap; docs-linkcheck groen (322 bestanden); diff-check groen.
  • Volledige lokale suite: 4241 geslaagd, 33 overgeslagen, één fout in een ongewijzigde Web Push-test door aanwezige VAPID-env. Die test opnieuw uitgevoerd zonder de drie VAPID-variabelen: 4/4 groen. De eerste lokale verify-run stopte op de standaard Node-heaplimiet; geen codefout. Dispatch-DB-integratietests en build beoordeeld via de groene CI-gates.
# APPROVED Geen blokkerende bevindingen in de diff van `f89bd976f426f2667177079da81978e6f044813d`. ## Findings - **MINOR — docs/runbooks/db-access-policy.md:521** — Vervang `postgres -V` door `SHOW server_version` via de verbinding met `scrum4me-postgres`. De binaryversie (mogelijk op de host) bewijst niet de versie van de draaiende server; de bindende spec en het plan vereisen die vergelijking met de CI-replay. ## Plan en productstandaarden Plan gekoppeld via pbi (Scrum4Me): IDEA-245 uitvoeringsplan rev 3. Ook getoetst aan de gekoppelde spec rev 5, spec-delta capture rev 2 en het in de PR genoemde plan-addendum r3. Geen references- of omitted-velden aangeleverd. De PR rondt T1–T5 af: ketenvalidatie, bundle-loader, ledgercontrole, beide provisioning-stages, guard-schakel 0001 en runbooks zijn aanwezig en sluiten aan op het plan. De beschermde IDEA-227-bestanden en bestaande dispatch-testbestanden zijn byte-ongewijzigd tegenover `6e0d6acc`. T6 (productie-uitrol) en T7 (scrum4me-mcp-vervolg) zijn expliciete vervolgstappen, geen ontbrekend werk binnen deze PR. Geen blokkerende afwijkingen in architectuur, patronen, tests of documentatie gevonden. ## Verificatie - PR en head-SHA via Forgejo bevestigd. - Forgejo CI-run **965**, op deze head: **Lint, Typecheck, Test & Build**, **DB Access Policy Gate** en **Queue Dispatch Guard Gate** groen. - Lokaal: 39 gerichte tests groen; typecheck groen met 8 GiB Node-heap; docs-linkcheck groen (322 bestanden); diff-check groen. - Volledige lokale suite: 4241 geslaagd, 33 overgeslagen, één fout in een ongewijzigde Web Push-test door aanwezige VAPID-env. Die test opnieuw uitgevoerd zonder de drie VAPID-variabelen: 4/4 groen. De eerste lokale verify-run stopte op de standaard Node-heaplimiet; geen codefout. Dispatch-DB-integratietests en build beoordeeld via de groene CI-gates.
docs(runbooks): compare the running server_version, not the binary (IDEA-245 review)
All checks were successful
CI / DB Access Policy Gate (pull_request) Successful in 1m54s
CI / Queue Dispatch Guard Gate (pull_request) Successful in 2m8s
CI / DB Access Production Sentinel (pull_request) Successful in 1m6s
CI / Deploy Manual (workflow_dispatch) (pull_request) Has been skipped
CI / Lint, Typecheck, Test & Build (pull_request) Successful in 8m58s
CI / Detect deploy-relevant changes (pull_request) Has been skipped
CI / Deploy Preview (PR) (pull_request) Has been skipped
CI / Deploy Production (main) (pull_request) Has been skipped
985931f45f
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
s4m-codex-reviewer left a comment

Verdict: COMMENT

Geen blokkerende codefindings gevonden. Goedkeuring blijft uit zolang de volledige verificatie onzeker is.

  • WARNING — .github/workflows/ci.yml:79: de job “Lint, Typecheck, Test & Build” in CI-run 966 staat voor head 985931f45fc05a3ba07985c4ad2b48a7b1e60ee6 nog op pending. T5 en plan-addendum r3 vereisen deze job groen; met name de build is nog niet bevestigd.

Plan gekoppeld via pbi (product Scrum4Me). Beoordeeld tegen het aangeleverde IDEA-245-plan rev 3, specs/idea-245-closed-schema-transitions, het capture-addendum rev 2 en plans/idea-245-plan-addendum-r3. De implementatie past bij de geclaimde scope T1–T5: validator/lint, ledger en loader, replay/capture, guard 0001, CI en runbooks. T6 (uitrol) en T7 (scrum4me-mcp) zijn expliciete vervolgwerkzaamheden en geen ontbrekende scope van deze PR.

Verificatie:

  • Lokaal: lint zonder errors (zes warnings buiten de diff), typecheck groen, 112 gerichte tests groen en doc-links groen.
  • Volledige lokale suite: 4240 tests geslaagd, 33 geskipt en twee omgevingsfouten. De historische-receipt-test slaagt na ophalen van de ontbrekende Git-historie; de push-test slaagt zonder geërfde VAPID-variabelen. Geen regressie aan deze PR toegeschreven. Live PPE-databasebewijs lokaal geskipt.
  • Forgejo run 966: DB Access Policy Gate, Queue Dispatch Guard Gate (adoption én chain) en Production Sentinel groen.
  • IDEA-227-bestanden en bestaande dispatch-testbestanden byte-ongewijzigd tegenover de PR-base.

De centrale contextloader en gedeelde ledgerlezer volgen de vastgelegde architectuur. Tests dekken onder meer HISTORY_MISSING zonder keten, checksum/prefix, NOOP, replay-mismatches, bundle-integriteit en de positieve en negatieve stopbewijsgevallen. Runbooks beschrijven de operatorcontext, uitrolvoorwaarden en het ontbreken van oude-bundle-rollback.

# Verdict: COMMENT Geen blokkerende codefindings gevonden. Goedkeuring blijft uit zolang de volledige verificatie onzeker is. - **WARNING — .github/workflows/ci.yml:79:** de job “Lint, Typecheck, Test & Build” in [CI-run 966](https://git.jp-visser.nl/janpeter/Scrum4Me/actions/runs/966) staat voor head `985931f45fc05a3ba07985c4ad2b48a7b1e60ee6` nog op pending. T5 en plan-addendum r3 vereisen deze job groen; met name de build is nog niet bevestigd. Plan gekoppeld via pbi (product Scrum4Me). Beoordeeld tegen het aangeleverde IDEA-245-plan rev 3, `specs/idea-245-closed-schema-transitions`, het capture-addendum rev 2 en `plans/idea-245-plan-addendum-r3`. De implementatie past bij de geclaimde scope T1–T5: validator/lint, ledger en loader, replay/capture, guard 0001, CI en runbooks. T6 (uitrol) en T7 (scrum4me-mcp) zijn expliciete vervolgwerkzaamheden en geen ontbrekende scope van deze PR. Verificatie: - Lokaal: lint zonder errors (zes warnings buiten de diff), typecheck groen, 112 gerichte tests groen en doc-links groen. - Volledige lokale suite: 4240 tests geslaagd, 33 geskipt en twee omgevingsfouten. De historische-receipt-test slaagt na ophalen van de ontbrekende Git-historie; de push-test slaagt zonder geërfde VAPID-variabelen. Geen regressie aan deze PR toegeschreven. Live PPE-databasebewijs lokaal geskipt. - Forgejo run 966: DB Access Policy Gate, Queue Dispatch Guard Gate (adoption én chain) en Production Sentinel groen. - IDEA-227-bestanden en bestaande dispatch-testbestanden byte-ongewijzigd tegenover de PR-base. De centrale contextloader en gedeelde ledgerlezer volgen de vastgelegde architectuur. Tests dekken onder meer HISTORY_MISSING zonder keten, checksum/prefix, NOOP, replay-mismatches, bundle-integriteit en de positieve en negatieve stopbewijsgevallen. Runbooks beschrijven de operatorcontext, uitrolvoorwaarden en het ontbreken van oude-bundle-rollback.
Author
Owner

CI run 966 green on head 985931f4 (all 8 jobs, including Lint, Typecheck, Test & Build, which was still pending at the time of the last review). The Queue Dispatch Guard Gate ran both stages, adoption and chain. This run applies to exactly the commit that will be merged (rollout step 0). The prod SHOW server_version = 17.9 (Debian 17.9-1.pgdg13+1) and matches the version the CI chain stage logged.

🤖 Generated with Claude Code

CI run **966** green on head `985931f4` (all 8 jobs, including Lint, Typecheck, Test & Build, which was still pending at the time of the last review). The Queue Dispatch Guard Gate ran both stages, `adoption` and `chain`. This run applies to exactly the commit that will be merged (rollout step 0). The prod `SHOW server_version` = `17.9 (Debian 17.9-1.pgdg13+1)` and matches the version the CI chain stage logged. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
janpeter/Scrum4Me!346
No description provided.