@intentius/sql-yodeler 0.3.0 → 0.4.0

package/dist/ci/render.js

@@ -71,7 +71,11 @@
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { APPROVAL_MODES } from "../config/define.js";
+import { RECORD_PLANS_ENV } from "../approval-mode/index.js";
+import { cloudToken, credentialsOf, roleVariables } from "../credentials.js";
 import { loadYodelConfig } from "../config/load.js";
+import { testFiles } from "../testing/files.js";
 import { emitYAMLEntry, parseYAMLDocument } from "@intentius/chant/yaml";
 import { Concurrency, Job as ActionsJob, Permissions, Service as ActionsService, Step, Workflow as ActionsWorkflow, } from "@intentius/chant-lexicon-github";
 import { githubSerializer } from "@intentius/chant-lexicon-github/serializer";
@@ -94,16 +98,54 @@ const SETUP_NODE = "actions/setup-node@v7";
 export const prefixOf = (env) => env.toUpperCase().replace(/[^A-Z0-9]/g, "_");
 /** DEV_CLICKHOUSE for dev on ClickHouse: what an environment's variables start with. */
 export const variablePrefix = (env, dialect) => `${prefixOf(env)}_${dialect.toUpperCase()}`;
-/** The variables a job reading `env` holds: the URL and the reader. */
-export const readerVariables = (env, dialect) => {
+/** The variables a job reading `env` holds: the URL and the reader (the variables credentials() names; none for a token-minted password). */
+export const readerVariables = (env, dialect, creds) => {
     const p = variablePrefix(env, dialect);
-    return [`${p}_URL`, `${p}_READER_USER`, `${p}_READER_PASSWORD`];
+    return [`${p}_URL`, ...(creds?.reader.variables ?? [`${p}_READER_USER`, `${p}_READER_PASSWORD`])];
 };
 /** The variables the apply job for `env` holds: the URL and the writer. */
-export const writerVariables = (env, dialect) => {
+export const writerVariables = (env, dialect, creds) => {
     const p = variablePrefix(env, dialect);
-    return [`${p}_URL`, `${p}_WRITER_USER`, `${p}_WRITER_PASSWORD`];
+    return [`${p}_URL`, ...(creds?.writer.variables ?? [`${p}_WRITER_USER`, `${p}_WRITER_PASSWORD`])];
 };
+// ── Cloud identity (#50) ────────────────────────────────────────────────────
+//
+// A role whose password is minted by a cloud token source (rds-iam,
+// cloud-sql-iam, entra) mints it with the cloud's command line, from the
+// job's identity. A job holding one gets an OIDC token from the forge: on
+// GitHub the workflow grants `id-token: write`; on GitLab the job declares
+// an ID token for the cloud's audience. Forgejo issues no OIDC token to a
+// job (its dialect drops `permissions:`), so there the runner's own cloud
+// identity mints.
+/** The GitLab ID token per cloud: its variable and its audience. */
+export const ID_TOKENS = {
+    "rds-iam": { variable: "AWS_ID_TOKEN", aud: "sts.amazonaws.com" },
+    "cloud-sql-iam": { variable: "GCP_ID_TOKEN", aud: "https://iam.googleapis.com/" },
+    entra: { variable: "AZURE_ID_TOKEN", aud: "api://AzureADTokenExchange" },
+};
+/** The cloud token sources the roles `held` mint from, each once, in order. */
+const cloudsOf = (envs, held) => [
+    ...new Set(held.map(([env, role]) => envs.credentials?.[env]?.[role].cloud).filter((c) => c !== undefined)),
+];
+/** A GitLab job's `id_tokens` for `clouds`. */
+const idTokens = (clouds) => Object.fromEntries(clouds.map((c) => [ID_TOKENS[c].variable, { aud: ID_TOKENS[c].aud }]));
+/** The roles a pull request's plan job for `env` holds: the environment's reader and the reader of the one it requires. */
+const planRoles = (waves, env) => [env, ...requiredOf(waves, env)].map((e) => [e, "reader"]);
+/** The roles a wave job for `env` holds: the writer, and the reader of the environment it requires. */
+const waveRoles = (waves, env) => [[env, "writer"], ...requiredOf(waves, env).map((e) => [e, "reader"])];
+/** The header lines saying what the cloud identity is for, when a job here holds a cloud-minted role. */
+function identityHeader(forge, clouds) {
+    if (clouds.length === 0)
+        return [];
+    const names = clouds.join(", ");
+    if (forge === "github")
+        return [`# Cloud identity: a password here is a ${names} token, minted from the job's`, "# identity, so the workflow grants id-token: write (an OIDC token)."];
+    if (forge === "gitlab")
+        return [`# Cloud identity: a password here is a ${names} token, minted from the job's`, `# identity: the jobs that hold one declare id_tokens (${clouds.map((c) => ID_TOKENS[c].variable).join(", ")}).`];
+    return [`# Cloud identity: a password here is a ${names} token. Forgejo gives a job no`, "# OIDC token, so the runner's own cloud identity mints it."];
+}
+/** The write probe a pull request job runs before its plan: it holds no writer for `envs`. */
+export const writeProbe = (envs) => `yodel config check ${envs.join(" ")} --write-probe`;
 const secret = (name) => `\${{ secrets.${name} }}`;
 const secrets = (names) => Object.fromEntries(names.map((n) => [n, secret(n)]));
 /**
@@ -154,6 +196,8 @@ export const REPLAY_SERVICE = {
 export const waitFor = (host, port) => `node -e 'const net = require("net"); let n = 0; (function t() { const s = net.connect(${String(port)}, "${host}", () => { s.end(); process.exit(0); }); s.on("error", () => { if (++n > 90) { console.error("${host}:${String(port)} did not answer"); process.exit(1); } setTimeout(t, 1000); }); })()'`;
 export const LINT = "yodel lint";
 export const REPLAY = `yodel lint --replay ${REPLAY_PROFILE} --reset`;
+/** yodel test (#54), after the replay check on the same throwaway server, its outcome as JUnit XML. */
+export const TEST = `yodel test --env ${REPLAY_PROFILE} --reset --junit yodel-test.xml`;
 /** Fails a pull request whose pipelines differ from what yodel ci renders. */
 export const CI_CHECK = "yodel ci --check";
 /**
@@ -225,7 +269,7 @@ const runner = (container, tc) => ({ "runs-on": "ubuntu-latest", ...(container ?
 function commentToken(forge) {
     return forge === "github" ? { GITHUB_TOKEN: "${{ github.token }}" } : { FORGEJO_TOKEN: "${{ github.token }}" };
 }
-function lintJob(forge, dialect, replay, tc) {
+function lintJob(forge, dialect, replay, tc, tests = false) {
     // With the replay check, the job runs in IMAGE on every forge and reaches
     // its replay server by the service's name on the job's own network. On
     // GitHub's VM the service would be on localhost through a published port,
@@ -254,31 +298,35 @@ function lintJob(forge, dialect, replay, tc) {
             ...steps,
             new Step({ name: `Wait for the replay server (${svc.name})`, run: waitFor(svc.name, svc.port) }),
             new Step({ name: "yodel lint --replay", run: REPLAY }),
+            ...(tests ? [new Step({ name: "yodel test", run: TEST })] : []),
         ],
     });
 }
 export function actionsReview(forge, envs_) {
     const { dialect, names: envs, replay, waves, jobs: own } = envs_;
     const tc = toolchainOf(envs_);
-    const jobs = { lint: lintJob(forge, dialect, replay, tc) };
+    const jobs = { lint: lintJob(forge, dialect, replay, tc, envs_.tests === true) };
     for (const env of envs) {
+        const read = [env, ...requiredOf(waves, env)];
         jobs[`plan-${env}`] = new ActionsJob({
             ...runner(inContainer(forge, tc), tc),
             // The plan shows where each migration has run: the required environment's reader too.
-            env: secrets([...[env, ...requiredOf(waves, env)].flatMap((e) => readerVariables(e, dialect)), ...WEBHOOK_VARIABLES]),
+            env: secrets([...read.flatMap((e) => readerVariables(e, dialect, envs_.credentials?.[e])), ...WEBHOOK_VARIABLES]),
             steps: [
                 // The plan explains what moved since an approval from git's history of migrations/.
                 ...setupSteps(inContainer(forge, tc), tc),
+                new Step({ name: "This job cannot write", run: writeProbe(read) }),
                 new Step({ name: `yodel plan ${env} --comment`, run: `yodel plan ${env} --comment`, env: commentToken(forge) }),
                 ...reportSteps(env, `plan-${env}`, tc),
             ],
         });
     }
     Object.assign(jobs, ownJobs(own?.actions, jobs, "actions"));
+    const clouds = cloudsOf(envs_, envs.flatMap((env) => planRoles(waves, env)));
     const workflow = new ActionsWorkflow({
         name: "yodel-pr",
         on: { pull_request: { branches: [MAIN] } },
-        permissions: new Permissions({ contents: "read", "pull-requests": "write" }),
+        permissions: new Permissions({ contents: "read", "pull-requests": "write", ...(clouds.length > 0 ? { "id-token": "write" } : {}) }),
         concurrency: new Concurrency({ group: "yodel-pr-${{ github.event.pull_request.number }}", "cancel-in-progress": true }),
         jobs,
     });
@@ -287,10 +335,13 @@ export function actionsReview(forge, envs_) {
         "#",
         "# Pull requests: yodel lint and the replay check (into a throwaway server the",
         "# lint job starts), and the plan comment per environment with the",
-        "# environment's reader credentials. No job here holds a writer.",
+        "# environment's reader credentials. No job here holds a writer, and each plan",
+        "# job shows it first: yodel config check --write-probe tries a write and",
+        "# fails the job when the server lets it through.",
         ...(forge === "forgejo"
             ? ["# The comment is posted with the job's own token (Forgejo gives a same-repository", "# pull request one that can comment)."]
             : []),
+        ...identityHeader(forge, clouds),
     ];
     return {
         path: `${forge === "github" ? ".github" : ".forgejo"}/workflows/yodel-pr.yml`,
@@ -300,6 +351,10 @@ export function actionsReview(forge, envs_) {
 // ── GitLab CI ───────────────────────────────────────────────────────────────
 export const GITLAB_WATCH_FILE = ".gitlab/yodel-watch.gitlab-ci.yml";
 export const GITLAB_APPLY_FILE = ".gitlab/yodel-apply.gitlab-ci.yml";
+/** The stage of the scheduled resume job in GITLAB_APPLY_FILE, as chant names it. */
+const RESUME_STAGE = "resume";
+/** The stage of the merge request job that records the plans a pr-review wave's review approves (#48), as chant names it. */
+const PLANS_STAGE = "plans";
 /** The stage of each wave's job in GITLAB_APPLY_FILE, as chant names it. */
 const waveStages = (waves) => waves.map((w, i) => `wave-${String(i + 1)}-${w.env}`);
 export function gitlabPipeline(envs_) {
@@ -325,18 +380,20 @@ export function gitlabPipeline(envs_) {
         rules: mr(),
         ...(replay
             ? {
-                script: [CI_CHECK, LINT, waitFor(svc.name, svc.port), REPLAY],
+                script: [CI_CHECK, LINT, waitFor(svc.name, svc.port), REPLAY, ...(envs_.tests === true ? [TEST] : [])],
                 services: [new GitLabService({ name: svc.image, alias: svc.name, variables: svc.env })],
                 variables: { [`${variablePrefix(REPLAY_PROFILE, dialect)}_URL`]: svc.url(svc.name), ...svc.jobEnv },
             }
             : { script: [CI_CHECK, LINT] }),
     }));
     for (const env of envs) {
+        const clouds = cloudsOf(envs_, planRoles(waves, env));
         jobs.set(`plan-${env}`, new GitLabJob({
             extends: ".yodel",
             stage: "review",
             rules: mr(),
-            script: [`yodel plan ${env} --comment`],
+            script: [writeProbe([env, ...requiredOf(waves, env)]), `yodel plan ${env} --comment`],
+            ...(clouds.length > 0 ? { id_tokens: idTokens(clouds) } : {}),
             after_script: [reportCommand(env, tc)],
             artifacts: new GitLabArtifacts({ name: reportArtifact(`plan-${env}`), when: "always", paths: [`${REPORT_DIR}/`] }),
         }));
@@ -356,19 +413,26 @@ export function gitlabPipeline(envs_) {
         throw new Error("gitlab: expected the jobs' YAML to start with their stages, review first");
     const derived = jobsYaml.slice(0, end + 2);
     // The stages this file's jobs use (review, then any the project's own jobs add), then the apply file's waves and the watch file's ops.
-    const stages = [...new Set([...derivedStages.map(String), ...waveStages(waves), "ops"])];
+    // A pr-review wave (#48) adds the merge request job that records the plans, in chant's stage "plans".
+    const plans = waves.some((w) => w.approval === "pr-review") ? [PLANS_STAGE] : [];
+    const stages = [...new Set([...derivedStages.map(String), ...plans, ...waveStages(waves), ...(envs_.resume ? [RESUME_STAGE] : []), "ops"])];
     const topLevel = [
         emitYAMLEntry("include", [{ local: GITLAB_APPLY_FILE }, { local: GITLAB_WATCH_FILE }]),
         emitYAMLEntry("stages", stages),
         emitYAMLEntry("variables", { GIT_DEPTH: "0" }),
     ];
     const yaml = `${serialize(new Map([["workflow", workflow]]))}\n${topLevel.join("\n\n")}\n\n${jobsYaml.slice(derived.length)}`;
-    const variables = envs.flatMap((env) => [
-        `#   ${readerVariables(env, dialect).join(", ")}: not protected (merge request`,
-        "#     pipelines run on unprotected branches), masked; no environment scope.",
-        `#   ${writerVariables(env, dialect).slice(1).join(", ")}: protected, masked,`,
-        `#     environment scope "${env}": only ${env}'s wave job declares that environment.`,
-    ]);
+    const variables = envs.flatMap((env) => {
+        const creds = envs_.credentials?.[env];
+        const writer = writerVariables(env, dialect, creds).slice(1);
+        return [
+            `#   ${readerVariables(env, dialect, creds).join(", ")}: not protected (merge request`,
+            "#     pipelines run on unprotected branches), masked; no environment scope.",
+            ...(writer.length > 0
+                ? [`#   ${writer.join(", ")}: protected, masked,`, `#     environment scope "${env}": only ${env}'s wave job declares that environment.`]
+                : []),
+        ];
+    });
     const header = [
         ...HEADER,
         "#",
@@ -380,12 +444,22 @@ export function gitlabPipeline(envs_) {
         "# protected or scoped to an environment, so the split between reader and",
         "# writer is in the variables' settings (Settings > CI/CD > Variables):",
         ...variables,
-        "#   GITLAB_TOKEN: a project access token with the api scope (Reporter), for",
-        "#     the plan comment and the drift watch's tracking issue; CI_JOB_TOKEN",
-        "#     cannot write merge request notes or issues.",
+        ...(envs_.resume
+            ? [
+                "#   GITLAB_TOKEN: a project access token with the api scope (Developer), for",
+                "#     the plan comment, the drift watch's tracking issue and the resume job's",
+                "#     retry of a wave whose approval arrived; CI_JOB_TOKEN cannot write merge",
+                "#     request notes or issues, or retry a job.",
+            ]
+            : [
+                "#   GITLAB_TOKEN: a project access token with the api scope (Reporter), for",
+                "#     the plan comment and the drift watch's tracking issue; CI_JOB_TOKEN",
+                "#     cannot write merge request notes or issues.",
+            ]),
         "# The jobs that hold no writer read with the reader: chant.config.ts picks an",
         "# environment's writer only under YODEL_CREDENTIALS=writer:<env>, which only",
         "# that environment's wave job sets.",
+        ...identityHeader("gitlab", cloudsOf(envs_, envs.flatMap((env) => [...planRoles(waves, env), ...waveRoles(waves, env), [env, "reader"]]))),
     ];
     return { path: ".gitlab-ci.yml", content: withHeader(header, yaml) };
 }
@@ -402,7 +476,7 @@ export const APPLY_PIPELINE = "yodel-apply";
  * The waves spec. What the file holds is the same for every forge; each
  * forge's jobs get their own variables on top (`variables`).
  */
-export function wavesSpec(waves, variables) {
+export function wavesSpec(waves, variables, resume) {
     const first = waves[0];
     if (!first)
         throw new Error("no waves to render");
@@ -417,8 +491,10 @@ export function wavesSpec(waves, variables) {
             runs: (w.targets ?? [w.env]).map((target) => ({ target, op: `migrate-${w.env}` })),
             gate: w.gate,
             ...(w.shares !== undefined && w.shares > 1 ? { shares: w.shares } : {}),
+            ...(w.approval !== undefined && w.approval !== "ledger" ? { approval: w.approval } : {}),
             ...(variables ? { environment: { name: w.env }, variables: variables(w.env) } : {}),
         })),
+        ...(resume ? { resume } : {}),
     };
 }
 /** The waves spec file and the apply pipeline on each forge. */
@@ -429,13 +505,19 @@ export async function applyPipelines(dir, envs) {
     const out = [{ path: WAVES_SPEC, content: `${JSON.stringify(wavesSpec(waves), null, 2)}\n` }];
     // A GitLab job already has the project's variables, a writer's only under its environment.
     const variables = (forge) => (env) => {
-        const required = waves.find((w) => w.env === env)?.requires;
+        const wave = waves.find((w) => w.env === env);
+        const required = wave?.requires;
         return {
             YODEL_CREDENTIALS: `writer:${env}`,
             ...APPLY_LOCK,
             ...(forge === "gitlab"
                 ? {}
-                : { ...secrets([...writerVariables(env, dialect), ...WEBHOOK_VARIABLES]), ...(required ? secrets(readerVariables(required, dialect)) : {}) }),
+                : {
+                    ...secrets([...writerVariables(env, dialect, envs.credentials?.[env]), ...WEBHOOK_VARIABLES]),
+                    ...(required ? secrets(readerVariables(required, dialect, envs.credentials?.[required])) : {}),
+                    // A pr-review wave (#48) reads the merged pull request's reviews with the job's token.
+                    ...(wave?.approval === "pr-review" ? { GITHUB_TOKEN: "${{ github.token }}" } : {}),
+                }),
         };
     };
     const header = [
@@ -446,13 +528,35 @@ export async function applyPipelines(dir, envs) {
         `# wave's gate policy is read from ${WAVES_SPEC} as the commit before the push`,
         "# has it (yodel.config.ts waves, rendered), and a wave that needs an approval",
         "# exits 3 with the chant approve command, so the waves after it do not run.",
-        "# Approve, push chant/lifecycle, and run the failed job again. These are the",
-        "# only jobs that hold a writer's credentials, one environment's each, with",
+        "# yodel approve <env> records the approval and starts the waiting job again",
+        "# (or approve, push chant/lifecycle, and run the failed job again). These are",
+        "# the only jobs that hold a writer's credentials, one environment's each, with",
         "# the reader of the environment before (waves[].requires): yodel apply refuses",
         "# a migration that environment's history does not record as applied.",
     ];
+    const resumeHeader = (forge) => [
+        ...HEADER,
+        "#",
+        `# On its schedule: chant run resume --op ${APPLY_PIPELINE} starts again each apply wave`,
+        "# that waits at its gate and whose approval has arrived since. It approves",
+        "# nothing; a wave whose approval does not count waits again.",
+        ...(forge === "github"
+            ? ["# It re-runs the run's failed jobs with the job's token (actions: write)."]
+            : ["# Forgejo has no re-run: it dispatches yodel-apply.yml again on main, with the", "# CHANT_FORGE_TOKEN secret, a token with the write:repository scope."]),
+    ];
+    const waveClouds = cloudsOf(envs, waves.flatMap((w) => waveRoles(waves, w.env)));
+    const plansHeader = [
+        ...HEADER,
+        "#",
+        "# A pull request into main, when a wave's approval is pr-review (yodel.config.ts",
+        "# waves[].approval): chant run wave --record-plans plans every wave at the pull",
+        "# request's head, as it will be after the merge, and records the digests on",
+        "# chant/lifecycle. After the merge, an approving review of that head by a writer",
+        "# other than its author approves the digest it recorded, and only that one. It",
+        "# holds no writer's credentials: it plans with each environment's reader.",
+    ];
     for (const forge of FORGES) {
-        const result = await generateOpWavesPipeline(wavesSpec(waves, variables(forge)), forge, {
+        const result = await generateOpWavesPipeline(wavesSpec(waves, variables(forge), envs.resume), forge, {
             specFile: WAVES_SPEC,
             image: tc.image,
             beforeScript: [...installLines(tc, forge), FETCH_APPROVALS],
@@ -462,7 +566,15 @@ export async function applyPipelines(dir, envs) {
             throw new Error(`${forge}: ${result.error ?? "generateOpWavesPipeline rendered nothing"}`);
         for (const file of result.files) {
             const at = forge === "gitlab" ? GITLAB_APPLY_FILE : `${forge === "github" ? ".github" : ".forgejo"}/workflows/${file.name}`;
-            out.push({ path: at, content: withHeader(header, withWaveReports(forge, file.yaml.endsWith("\n") ? file.yaml : `${file.yaml}\n`, waves, tc)) });
+            const yaml = file.yaml.endsWith("\n") ? file.yaml : `${file.yaml}\n`;
+            // The resume workflow (GitHub, Forgejo) has no wave job to report on.
+            if (forge !== "gitlab" && file.name === `${APPLY_PIPELINE}-resume.yml`)
+                out.push({ path: at, content: withHeader(resumeHeader(forge), yaml) });
+            // The pull request workflow that records the plans a review approves (#48).
+            else if (forge !== "gitlab" && file.name === `${APPLY_PIPELINE}-plans.yml`)
+                out.push({ path: at, content: withHeader(plansHeader, withPlansReaders(forge, yaml, waves, dialect, envs)) });
+            else
+                out.push({ path: at, content: withHeader([...header, ...identityHeader(forge, waveClouds)], withWaveReports(forge, yaml, waves, tc, envs)) });
         }
     }
     return out;
@@ -475,7 +587,7 @@ export async function applyPipelines(dir, envs) {
  * back chant's text unchanged before anything is added, so a change in
  * chant's emitter fails here instead of rendering something else.
  */
-function withWaveReports(forge, yaml, waves, tc) {
+function withWaveReports(forge, yaml, waves, tc, envs = {}) {
     // A wide wave's jobs are wave-<k>-<env>-decide and -share-<i>.
     const envOf = (job) => waves.find((w, i) => new RegExp(`^wave-${String(i + 1)}-${w.env.replace(/[^A-Za-z0-9]/g, "\\$&")}(-decide|-share-\\d+)?$`).test(job))?.env;
     const body = yaml.search(/^[^#\n]/m);
@@ -485,11 +597,20 @@ function withWaveReports(forge, yaml, waves, tc) {
         const emit = (d) => `${header}${Object.entries(d).map(([k, v]) => emitYAMLEntry(k, v)).join("\n\n")}\n`;
         if (emit(doc) !== yaml)
             throw new Error("gitlab: the apply waves do not emit back to chant's text");
+        // The merge request job that records the plans a review approves (#48): the waves as after the merge.
+        const record = doc[`${APPLY_PIPELINE}-record-plans`];
+        if (record) {
+            record.variables = { ...(record.variables ?? {}), [RECORD_PLANS_ENV]: "1" };
+            const readers = cloudsOf(envs, [...new Set(waves.map((w) => w.env))].map((e) => [e, "reader"]));
+            if (readers.length > 0)
+                record.id_tokens = idTokens(readers);
+        }
         for (const [name, job] of Object.entries(doc)) {
             const env = envOf(name);
             if (!env || typeof job !== "object" || job === null)
                 continue;
-            Object.assign(job, { after_script: [reportCommand(env, tc)], artifacts: { name: reportArtifact(name), when: "always", paths: [`${REPORT_DIR}/`] } });
+            const clouds = cloudsOf(envs, waveRoles(waves, env));
+            Object.assign(job, { after_script: [reportCommand(env, tc)], artifacts: { name: reportArtifact(name), when: "always", paths: [`${REPORT_DIR}/`] }, ...(clouds.length > 0 ? { id_tokens: idTokens(clouds) } : {}) });
         }
         return emit(doc);
     }
@@ -497,8 +618,9 @@ function withWaveReports(forge, yaml, waves, tc) {
     if (at < 0)
         throw new Error(`${forge}: the apply waves have no jobs`);
     const jobs = doc.jobs;
-    const emit = () => `${yaml.slice(0, at + 1)}${emitYAMLEntry("jobs", jobs)}\n`;
-    if (emit() !== yaml)
+    const top = yaml.slice(0, at + 1);
+    const emitJobs = () => `${emitYAMLEntry("jobs", jobs)}\n`;
+    if (`${top}${emitJobs()}` !== yaml)
         throw new Error(`${forge}: the apply waves do not emit back to chant's text`);
     for (const [name, job] of Object.entries(jobs)) {
         const env = envOf(name);
@@ -508,7 +630,33 @@ function withWaveReports(forge, yaml, waves, tc) {
         // chant's forgejo output is already in Forgejo's dialect, so the action is named as the forgejo lexicon names it.
         { name: "Keep the report", if: "always()", uses: forge === "forgejo" ? `https://code.forgejo.org/${UPLOAD_ARTIFACT}` : UPLOAD_ARTIFACT, with: { name: reportArtifact(name), path: REPORT_DIR, "if-no-files-found": "ignore" } });
     }
-    return emit();
+    return `${withIdToken(forge, top, cloudsOf(envs, waves.flatMap((w) => waveRoles(waves, w.env))))}${emitJobs()}`;
+}
+/**
+ * The plans workflow (GitHub, Forgejo) for a pr-review wave (#48): chant's,
+ * with each environment's reader (the waves are planned on every one, and a
+ * wave reads the history of the one it requires) and {@link RECORD_PLANS_ENV}
+ * on its job. The output is parsed and emitted again, checked first to give
+ * back chant's text unchanged.
+ */
+function withPlansReaders(forge, yaml, waves, dialect, creds = {}) {
+    const at = yaml.indexOf("\njobs:\n");
+    if (at < 0)
+        throw new Error(`${forge}: the plans workflow has no jobs`);
+    const doc = parseYAMLDocument(yaml);
+    const top = yaml.slice(0, at + 1);
+    const emitJobs = () => `${emitYAMLEntry("jobs", doc.jobs)}\n`;
+    if (`${top}${emitJobs()}` !== yaml)
+        throw new Error(`${forge}: the plans workflow does not emit back to chant's text`);
+    const job = doc.jobs["record-plans"];
+    if (!job)
+        throw new Error(`${forge}: the plans workflow has no record-plans job`);
+    const envs = [...new Set(waves.map((w) => w.env))];
+    const steps = job.steps;
+    delete job.steps;
+    Object.assign(job, { env: { [RECORD_PLANS_ENV]: "1", ...secrets(envs.flatMap((e) => readerVariables(e, dialect, creds.credentials?.[e]))) }, steps });
+    // A reader whose password is a cloud token (#50) is minted from the job's identity.
+    return `${withIdToken(forge, top, cloudsOf(creds, envs.map((e) => [e, "reader"])))}${emitJobs()}`;
 }
 /** yodel.config.ts `waves`, checked against the environments; one wave per environment, gate `always`, without it. */
 export async function readWaves(dir, envs) {
@@ -527,28 +675,28 @@ export async function readWaves(dir, envs) {
         const requires = w.requires === false ? undefined : w.requires === undefined ? (i > 0 ? String(all[i - 1]?.env) : undefined) : typeof w.requires === "string" ? w.requires : JSON.stringify(w.requires);
         if (requires !== undefined && !envs.includes(requires))
             throw new Error(`yodel.config.ts: waves[${String(i)}].requires ${requires} is not an environment (${envs.join(", ")})`);
-        return { env, gate, ...(requires ? { requires } : {}), ...(typeof w.shares === "number" && w.shares > 1 ? { shares: w.shares } : {}) };
+        const approval = w.approval;
+        if (approval !== undefined && !APPROVAL_MODES.includes(approval))
+            throw new Error(`yodel.config.ts: waves[${String(i)}].approval ${String(w.approval)} is not ${APPROVAL_MODES.join(", ")}`);
+        return { env, gate, ...(requires ? { requires } : {}), ...(typeof w.shares === "number" && w.shares > 1 ? { shares: w.shares } : {}), ...(approval && approval !== "ledger" ? { approval } : {}) };
     });
 }
 /**
- * Each wave of an environment with a tenant set (#56), with a run per
- * tenant. A set given by a query is read from the server now, with the
- * environment's profile: run yodel ci again when the tenants change.
+ * Each wave of an environment with a tenant set (#56), with its runs: a
+ * run per tenant of a list or a file, or for a set given by a query,
+ * `shares` slots (one without) that read the tenants when the wave runs.
+ * The query is not run here, so the pipeline stays the same as tenants come
+ * and go; a list or a file is in the repository, and changing it is
+ * rendering again.
  */
 export async function withTenants(dir, waves) {
     const { loadProject } = await import("../project.js");
-    const { listTenants, tenantTarget } = await import("../tenants/index.js");
+    const { waveTargets } = await import("../tenants/wave.js");
     const project = await loadProject(dir);
     const out = [];
     for (const w of waves) {
-        const tenants = await listTenants(project, w.env);
-        if (tenants === undefined) {
-            out.push(w);
-            continue;
-        }
-        if (tenants.length === 0)
-            throw new Error(`${w.env}'s tenant set lists no tenant, so its wave would apply nothing`);
-        out.push({ ...w, targets: tenants.map((t) => tenantTarget(w.env, t)) });
+        const targets = await waveTargets(project, w.env, w.shares);
+        out.push(targets === undefined ? w : { ...w, targets });
     }
     return out;
 }
@@ -558,16 +706,43 @@ export async function withTenants(dir, waves) {
  * writer's only under its environment, which the watch does not declare), and
  * `NAME: $NAME` there would refer to itself.
  */
-export function watchSpec(env, dialect, forge) {
+export function watchSpec(env, dialect, forge, creds) {
     if (forge === "gitlab")
         return { name: `watch-${env}` };
     // The job's token, for the tracking issue: GitHub grants it issues: write here, Forgejo's can write already.
     return {
         name: `watch-${env}`,
-        variables: { ...secrets([...readerVariables(env, dialect), ...WEBHOOK_VARIABLES]), GITHUB_TOKEN: "${{ github.token }}" },
-        ...(forge === "github" ? { permissions: { issues: "write" } } : {}),
+        variables: { ...secrets([...readerVariables(env, dialect, creds), ...WEBHOOK_VARIABLES]), GITHUB_TOKEN: "${{ github.token }}" },
+        ...(forge === "github" ? { permissions: { issues: "write", ...(creds?.reader.cloud ? { "id-token": "write" } : {}) } } : {}),
     };
 }
+/** A GitHub workflow's top-level `permissions:` with `id-token: write` added, when a job holds a cloud-minted role. */
+function withIdToken(forge, top, clouds) {
+    if (forge !== "github" || clouds.length === 0)
+        return top;
+    const added = top.replace(/^permissions:\n((?: {2}\S.*\n)*)/m, (_m, scopes) => `permissions:\n${scopes}  id-token: write\n`);
+    if (added === top)
+        throw new Error("github: the apply waves have no top-level permissions to add id-token: write to");
+    return added;
+}
+/** The GitLab watch file with `id_tokens` on each watch job whose reader is cloud-minted. Parsed and emitted again, checked against chant's text first. */
+function withWatchIdTokens(yaml, envs) {
+    const clouds = (env) => cloudsOf(envs, [[env, "reader"]]);
+    if (!envs.names.some((env) => clouds(env).length > 0))
+        return yaml;
+    const body = yaml.search(/^[^#\n]/m);
+    const header = yaml.slice(0, body);
+    const doc = parseYAMLDocument(yaml);
+    const emit = (d) => `${header}${Object.entries(d).map(([k, v]) => emitYAMLEntry(k, v)).join("\n\n")}\n`;
+    if (emit(doc) !== yaml)
+        throw new Error("gitlab: the watch file does not emit back to chant's text");
+    for (const env of envs.names) {
+        const job = doc[`watch-${env}`];
+        if (clouds(env).length > 0 && typeof job === "object" && job !== null)
+            Object.assign(job, { id_tokens: idTokens(clouds(env)) });
+    }
+    return emit(doc);
+}
 export async function watchPipelines(dir, envs_) {
     const { dialect, names: envs } = envs_;
     const tc = toolchainOf(envs_);
@@ -584,19 +759,22 @@ export async function watchPipelines(dir, envs_) {
             throw new Error(`${forge}: ${result.error ?? "generateOpsPipeline rendered nothing"}`);
         for (const file of result.files) {
             const at = forge === "gitlab" ? GITLAB_WATCH_FILE : `${forge === "github" ? ".github" : ".forgejo"}/workflows/${file.name}`;
-            out.push({ path: at, content: `${HEADER.join("\n")}\n${file.yaml.endsWith("\n") ? file.yaml : `${file.yaml}\n`}` });
+            const yaml = file.yaml.endsWith("\n") ? file.yaml : `${file.yaml}\n`;
+            out.push({ path: at, content: `${HEADER.join("\n")}\n${forge === "gitlab" ? withWatchIdTokens(yaml, envs_) : yaml}` });
         }
     };
     // `chant run` exits 0 when a watch finds drift; the last line, yodel drift, fails the job then.
     for (const forge of ["github", "forgejo"]) {
         for (const env of envs)
-            await emit(forge, [watchSpec(env, dialect, forge)], [watchDrift(env)]);
+            await emit(forge, [watchSpec(env, dialect, forge, envs_.credentials?.[env])], [watchDrift(env)]);
     }
     // GitLab: one file for every watch, so the last line takes the environment from the job's own name.
     await emit("gitlab", envs.map((env) => watchSpec(env, dialect, "gitlab")), [watchDrift('"${CI_JOB_NAME#watch-}"')]);
     return out;
 }
 // ── The project ─────────────────────────────────────────────────────────────
+/** Whether the project has a test file for yodel test (tests/*.test.ts). */
+const hasTests = (dir) => testFiles(dir).length > 0;
 /** The dialect and the environments chant.config.ts declares, in order. */
 export async function environments(dir) {
     const { loadChantConfig } = await import("@intentius/chant/config");
@@ -617,16 +795,35 @@ export async function environments(dir) {
         }
     }
     const ci = (await readConfig(dir))?.ci;
+    const credentials = credentialsIn(sql?.profiles ?? {}, envs);
     return {
         dialect,
         names: envs,
+        ...(Object.keys(credentials).length > 0 ? { credentials } : {}),
         replay,
+        ...(hasTests(dir) ? { tests: true } : {}),
         waves: await withTenants(dir, await readWaves(dir, envs)),
         forges: ci?.forges ?? FORGES,
         ...(ci?.jobs ? { jobs: await loadProjectJobs(dir, ci.jobs) } : {}),
         ...(ci?.image ? { image: ci.image } : {}),
+        ...(ci?.resume ? { resume: { schedule: ci.resume.schedule } } : {}),
     };
 }
+/** The roles of each environment whose profile is made with credentials(). */
+export function credentialsIn(profiles, envs) {
+    const out = {};
+    for (const env of envs) {
+        const c = credentialsOf(profiles[env]);
+        if (!c)
+            continue;
+        const needs = (role) => {
+            const cloud = cloudToken(c, role);
+            return { variables: roleVariables(c, role), ...(cloud ? { cloud } : {}) };
+        };
+        out[env] = { reader: needs("reader"), writer: needs("writer") };
+    }
+    return out;
+}
 /** yodel.config.ts, checked; undefined when the project has none. */
 async function readConfig(dir) {
     return (await loadYodelConfig(dir))?.config;