@intentius/chant 0.124.92 → 0.124.94
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/__golden__/notify-defaults-plain.json +52 -0
- package/dist/__golden__/notify-defaults-relay.json +92 -0
- package/dist/ci-job-guard.d.ts +22 -8
- package/dist/ci-job-guard.d.ts.map +1 -1
- package/dist/ci-job-guard.js +93 -49
- package/dist/ci-jobs.d.ts +22 -0
- package/dist/ci-jobs.d.ts.map +1 -1
- package/dist/ci-jobs.js +23 -0
- package/dist/ci-product.d.ts +41 -1
- package/dist/ci-product.d.ts.map +1 -1
- package/dist/ci-product.js +45 -5
- package/dist/cli/handlers/run-wave.js +17 -3
- package/dist/cli/main.d.ts.map +1 -1
- package/dist/cli/main.js +4 -1
- package/dist/components/product-pipeline.d.ts +30 -0
- package/dist/components/product-pipeline.d.ts.map +1 -1
- package/dist/components/product-pipeline.js +28 -3
- package/dist/floor-table.data.d.ts.map +1 -1
- package/dist/floor-table.data.js +17 -4
- package/dist/gate-resume-run.d.ts +7 -0
- package/dist/gate-resume-run.d.ts.map +1 -1
- package/dist/gate-resume-run.js +42 -3
- package/dist/lexicon.d.ts +64 -1
- package/dist/lexicon.d.ts.map +1 -1
- package/dist/lifecycle/gate-applied.d.ts +18 -0
- package/dist/lifecycle/gate-applied.d.ts.map +1 -1
- package/dist/notify.d.ts +8 -0
- package/dist/notify.d.ts.map +1 -1
- package/dist/notify.js +8 -3
- package/dist/op/before-merge.d.ts +8 -0
- package/dist/op/before-merge.d.ts.map +1 -1
- package/dist/op/before-merge.js +6 -0
- package/dist/op/gate-run-locator.d.ts +17 -0
- package/dist/op/gate-run-locator.d.ts.map +1 -1
- package/dist/op/index.d.ts +4 -2
- package/dist/op/index.d.ts.map +1 -1
- package/dist/op/index.js +3 -2
- package/dist/op/op-waves-names.d.ts +65 -2
- package/dist/op/op-waves-names.d.ts.map +1 -1
- package/dist/op/op-waves-names.js +129 -0
- package/dist/op/op-waves-remainder.d.ts +110 -0
- package/dist/op/op-waves-remainder.d.ts.map +1 -0
- package/dist/op/op-waves-remainder.js +120 -0
- package/dist/op/op-waves-render-spec.d.ts +63 -5
- package/dist/op/op-waves-render-spec.d.ts.map +1 -1
- package/dist/op/op-waves-render-spec.js +68 -10
- package/dist/op/op-waves-run.d.ts +29 -1
- package/dist/op/op-waves-run.d.ts.map +1 -1
- package/dist/op/op-waves-run.js +194 -6
- package/dist/op/op-waves-split-resume.d.ts +57 -0
- package/dist/op/op-waves-split-resume.d.ts.map +1 -0
- package/dist/op/op-waves-split-resume.js +94 -0
- package/dist/op/op-waves-stand-down.d.ts +9 -1
- package/dist/op/op-waves-stand-down.d.ts.map +1 -1
- package/dist/op/op-waves-stand-down.js +14 -2
- package/dist/op/op-waves.d.ts +38 -2
- package/dist/op/op-waves.d.ts.map +1 -1
- package/dist/op/op-waves.js +13 -2
- package/dist/release-floors.d.ts +9 -1
- package/dist/release-floors.d.ts.map +1 -1
- package/dist/release-floors.js +9 -1
- package/dist/wave-runtime.mjs +368 -368
- package/package.json +1 -1
- package/src/__golden__/notify-defaults-plain.json +52 -0
- package/src/__golden__/notify-defaults-relay.json +92 -0
- package/src/ci-job-guard.default-branch.test.ts +125 -0
- package/src/ci-job-guard.ts +64 -10
- package/src/ci-jobs.ts +26 -0
- package/src/ci-product.ts +54 -5
- package/src/cli/handlers/run-wave.ts +16 -3
- package/src/cli/main.ts +4 -1
- package/src/components/product-pipeline.ts +49 -4
- package/src/floor-table.data.ts +17 -4
- package/src/gate-resume-run.ts +38 -3
- package/src/lexicon.ts +64 -1
- package/src/lifecycle/gate-applied.ts +16 -0
- package/src/notify-bundle.test.ts +3 -2
- package/src/notify-relay-name.test.ts +72 -0
- package/src/notify.ts +16 -3
- package/src/op/before-merge.ts +12 -0
- package/src/op/gate-run-locator.ts +14 -0
- package/src/op/index.ts +6 -1
- package/src/op/op-waves-names.ts +130 -2
- package/src/op/op-waves-remainder.test.ts +342 -0
- package/src/op/op-waves-remainder.ts +146 -0
- package/src/op/op-waves-render-spec.test.ts +107 -0
- package/src/op/op-waves-render-spec.ts +81 -10
- package/src/op/op-waves-run.ts +204 -7
- package/src/op/op-waves-split-resume.test.ts +149 -0
- package/src/op/op-waves-split-resume.ts +109 -0
- package/src/op/op-waves-stand-down.ts +15 -2
- package/src/op/op-waves.ts +46 -3
- package/src/release-floors.ts +13 -1
package/src/op/op-waves-names.ts
CHANGED
|
@@ -43,7 +43,8 @@ export type OpWavesJobRole =
|
|
|
43
43
|
| "apply-status"
|
|
44
44
|
| "stale-notes"
|
|
45
45
|
| "before-merge-done"
|
|
46
|
-
| "control"
|
|
46
|
+
| "control"
|
|
47
|
+
| "resume";
|
|
47
48
|
|
|
48
49
|
/** One job the generator names (#5022). */
|
|
49
50
|
export interface OpWavesJobRef {
|
|
@@ -55,7 +56,9 @@ export interface OpWavesJobRef {
|
|
|
55
56
|
* job. `plan`, `gate`, `apply`, `record`: a split wave's jobs before merge
|
|
56
57
|
* (`apply` with `share` or `group` for a wide wave's). `policy` (GitLab),
|
|
57
58
|
* `evidence`: the jobs of a wave's checks. The rest are the jobs after
|
|
58
|
-
* or beside the waves
|
|
59
|
+
* or beside the waves; `resume` (#5034) is the scheduled job that starts
|
|
60
|
+
* a waiting wave's job again, `resume` in its own workflow on GitHub and
|
|
61
|
+
* Forgejo and `<spec>-resume` on GitLab.
|
|
59
62
|
*/
|
|
60
63
|
role: OpWavesJobRole;
|
|
61
64
|
/** The wave's number from 1, and its name, on every job but the stale and control jobs and the before-merge done job. */
|
|
@@ -176,6 +179,131 @@ export function opWavesWorkflowFile(spec: Pick<OpWavesSpec, "name">, file: strin
|
|
|
176
179
|
return file;
|
|
177
180
|
}
|
|
178
181
|
|
|
182
|
+
/**
|
|
183
|
+
* The file the resume workflow goes in (#5034, GitHub and Forgejo):
|
|
184
|
+
* `resumeWorkflowFile`, such as terragucci's `terragucci-resume.yml`, else
|
|
185
|
+
* `<spec>-resume.yml`. Refused when it is the waves' own file.
|
|
186
|
+
*/
|
|
187
|
+
export function opWavesResumeWorkflowFile(spec: Pick<OpWavesSpec, "name">, file: string | undefined, wavesFile: string): string {
|
|
188
|
+
if (file === undefined) return `${spec.name}-resume.yml`;
|
|
189
|
+
if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\.ya?ml$/.test(file)) throw new Error(`resumeWorkflowFile ${JSON.stringify(file)} is a workflow file's name, like terragucci-resume.yml, in the forge's workflow directory`);
|
|
190
|
+
if (file === wavesFile) throw new Error(`resumeWorkflowFile ${JSON.stringify(file)} is the waves' own workflow; the resume runs on a schedule of its own`);
|
|
191
|
+
return file;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* The product's own jobs the first wave's jobs need (#5032), such as
|
|
196
|
+
* terragucci's `check`: checked as job names of the forge, each once.
|
|
197
|
+
* Absent or empty: none, and the jobs render as before.
|
|
198
|
+
*/
|
|
199
|
+
export function opWavesFirstWaveNeeds(given: readonly string[] | undefined, forge: "github" | "forgejo" | "gitlab"): string[] {
|
|
200
|
+
if (given === undefined) return [];
|
|
201
|
+
if (!Array.isArray(given)) throw new Error("firstWaveNeeds is a list of the product's job names");
|
|
202
|
+
const github = forge !== "gitlab";
|
|
203
|
+
for (const n of given) {
|
|
204
|
+
const ok = typeof n === "string" && (github ? /^[A-Za-z_][A-Za-z0-9_-]*$/.test(n) : /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(n) && !GITLAB_KEYWORDS.has(n));
|
|
205
|
+
if (!ok) throw new Error(`firstWaveNeeds names ${JSON.stringify(n)}, which is not a job name of letters, digits, _ and -${github ? ", starting with a letter or _" : ", and no GitLab keyword"}`);
|
|
206
|
+
}
|
|
207
|
+
if (new Set(given).size !== given.length) throw new Error(`firstWaveNeeds names a job twice: ${given.join(", ")}`);
|
|
208
|
+
return [...given];
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* The forge token a wave job's command step gets (#5044): with it, the
|
|
213
|
+
* jobs that run only the default branch's code (a push's wave, deciding,
|
|
214
|
+
* share and job group jobs; a split wave's gate and record jobs) hand their
|
|
215
|
+
* command step the job's token as `GITHUB_TOKEN`, so the spec's `respond`
|
|
216
|
+
* posts and a product's hooks can read the forge, and the job asks for
|
|
217
|
+
* `permissions` on top of chant's own. A split wave's plan and applying jobs
|
|
218
|
+
* run the change's code and never get it. GitHub and Forgejo only.
|
|
219
|
+
*/
|
|
220
|
+
export interface OpWavesCommandToken {
|
|
221
|
+
/** GitHub's permission scopes the jobs ask for beside chant's own, such as `{ "pull-requests": "write", actions: "read" }`. `contents` and `id-token` are chant's. */
|
|
222
|
+
permissions?: Record<string, "read" | "write">;
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** The GitHub permission scopes a product may add with {@link OpWavesCommandToken}. `contents` and `id-token` stay chant's. */
|
|
226
|
+
const COMMAND_TOKEN_SCOPES = new Set(["actions", "attestations", "checks", "deployments", "discussions", "issues", "packages", "pages", "pull-requests", "repository-projects", "security-events", "statuses"]);
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* {@link OpWavesCommandToken}'s permissions, checked (#5044): each a scope
|
|
230
|
+
* GitHub knows that chant does not set itself, `read` or `write`. Undefined
|
|
231
|
+
* when there is no token to give. GitLab refuses it, since its jobs read
|
|
232
|
+
* `CHANT_FORGE_TOKEN`, a CI/CD variable.
|
|
233
|
+
*/
|
|
234
|
+
export function opWavesCommandToken(token: OpWavesCommandToken | undefined, forge: "github" | "forgejo" | "gitlab"): Record<string, "read" | "write"> | undefined {
|
|
235
|
+
if (token === undefined) return undefined;
|
|
236
|
+
if (forge === "gitlab") throw new Error("commandToken gives a GitHub or Forgejo wave job its token; a GitLab job reads CHANT_FORGE_TOKEN, a CI/CD variable, so leave it out");
|
|
237
|
+
if (token === null || typeof token !== "object" || Array.isArray(token)) throw new Error("commandToken is { permissions }");
|
|
238
|
+
const permissions = token.permissions ?? {};
|
|
239
|
+
if (permissions === null || typeof permissions !== "object" || Array.isArray(permissions)) throw new Error("commandToken.permissions maps a permission scope to read or write");
|
|
240
|
+
for (const [scope, level] of Object.entries(permissions)) {
|
|
241
|
+
if (scope === "contents" || scope === "id-token") throw new Error(`commandToken.permissions names ${scope}, which chant sets on the wave jobs itself`);
|
|
242
|
+
if (!COMMAND_TOKEN_SCOPES.has(scope)) throw new Error(`commandToken.permissions names ${JSON.stringify(scope)}, which is not a GitHub permission scope`);
|
|
243
|
+
if (level !== "read" && level !== "write") throw new Error(`commandToken.permissions.${scope} is ${JSON.stringify(level)}; give read or write`);
|
|
244
|
+
}
|
|
245
|
+
return { ...permissions };
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* The control job's group a product names (#5053), checked, with `{commit}`
|
|
250
|
+
* put in as `commit`, the forge's expression of the commit the job tells the
|
|
251
|
+
* control repo about. Undefined when none. One line; a spec without
|
|
252
|
+
* `control` has no job to put it on.
|
|
253
|
+
*/
|
|
254
|
+
export function opWavesControlGroup(group: string | undefined, hasControl: boolean, commit: string): string | undefined {
|
|
255
|
+
if (group === undefined) return undefined;
|
|
256
|
+
if (typeof group !== "string" || group.trim() === "" || /[\r\n]/.test(group)) throw new Error(`controlGroup ${JSON.stringify(group)} is one line naming the control job's group`);
|
|
257
|
+
if (!hasControl) throw new Error("controlGroup names the control job's group, and the spec has no control");
|
|
258
|
+
return group.split("{commit}").join(commit);
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/**
|
|
262
|
+
* GitLab (#5053): the resume job's `resource_group` a product names, checked.
|
|
263
|
+
* Undefined when none. GitHub and Forgejo refuse it, since their resume
|
|
264
|
+
* workflow has its own group, `<spec>-resume`.
|
|
265
|
+
*/
|
|
266
|
+
export function opWavesResumeGroup(group: string | undefined, hasResume: boolean, forge: "github" | "forgejo" | "gitlab"): string | undefined {
|
|
267
|
+
if (group === undefined) return undefined;
|
|
268
|
+
if (forge !== "gitlab") throw new Error("resumeGroup is the GitLab resume job's resource_group; the GitHub and Forgejo resume workflow has its own concurrency group, <spec>-resume");
|
|
269
|
+
if (typeof group !== "string" || group.trim() === "" || /[\r\n]/.test(group)) throw new Error(`resumeGroup ${JSON.stringify(group)} is one line naming the resume job's resource_group`);
|
|
270
|
+
if (!hasResume) throw new Error("resumeGroup names the resume job's resource_group, and the spec has no resume");
|
|
271
|
+
return group;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/**
|
|
275
|
+
* GitLab (#5045): the `cache:` a product gives the wave jobs that run the
|
|
276
|
+
* wave's command, one entry or a list of them as GitLab takes them, such as
|
|
277
|
+
* terragucci's `{ key: terragucci-terragrunt, paths: [.terragrunt-cache/] }`.
|
|
278
|
+
* Each entry is a mapping with `paths` or `key`. Undefined when none.
|
|
279
|
+
*/
|
|
280
|
+
export function opWavesGitlabCache(cache: Record<string, unknown> | Array<Record<string, unknown>> | undefined): Record<string, unknown> | Array<Record<string, unknown>> | undefined {
|
|
281
|
+
if (cache === undefined) return undefined;
|
|
282
|
+
const entries = Array.isArray(cache) ? cache : [cache];
|
|
283
|
+
if (entries.length === 0) throw new Error("cache is a GitLab cache entry or a list of them; leave it out for none");
|
|
284
|
+
for (const entry of entries) {
|
|
285
|
+
if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw new Error("cache holds GitLab cache entries, each a mapping such as { key, paths }");
|
|
286
|
+
if (entry.paths === undefined && entry.key === undefined) throw new Error("a cache entry names its paths or its key");
|
|
287
|
+
}
|
|
288
|
+
return cache;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
/** Refuse a product job of {@link opWavesFirstWaveNeeds} that is a job the generator writes (#5032). */
|
|
292
|
+
export function assertFirstWaveNeedsOutside(needs: readonly string[], jobs: Iterable<string>): void {
|
|
293
|
+
const mine = new Set(jobs);
|
|
294
|
+
for (const n of needs) if (mine.has(n)) throw new Error(`firstWaveNeeds names ${n}, a job of the waves themselves; name the product's own jobs, such as its check`);
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/**
|
|
298
|
+
* GitHub and Forgejo: the condition a first-wave job runs under with
|
|
299
|
+
* {@link opWavesFirstWaveNeeds} (#5032). Each product job passed; in a
|
|
300
|
+
* dispatched run (before merge), one that did not run is no hold, since a
|
|
301
|
+
* product's check runs on its pushes and pull requests.
|
|
302
|
+
*/
|
|
303
|
+
export function githubFirstWaveIf(needs: readonly string[]): string {
|
|
304
|
+
return ["!cancelled()", ...needs.map((n) => `(needs.${n}.result == 'success' || (github.event_name == 'workflow_dispatch' && needs.${n}.result == 'skipped'))`)].join(" && ");
|
|
305
|
+
}
|
|
306
|
+
|
|
179
307
|
const GITLAB_KEYWORDS = new Set(["default", "include", "stages", "variables", "workflow", "image", "services", "cache", "before_script", "after_script", "spec", "pages"]);
|
|
180
308
|
|
|
181
309
|
/** A job of a pipeline as {@link opWavesNamer} reads it: an `opWaveJobs` job, or a split one with its phase. */
|
|
@@ -0,0 +1,342 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* #5047: the record of an apply under an approval is chant's own. Under
|
|
3
|
+
* `approvals.remainder` (with `approvals.spend`, both read at base) the
|
|
4
|
+
* applied line names each change the approved plans make, the job that
|
|
5
|
+
* applies the whole wave (a split wave's record job) writes how the apply
|
|
6
|
+
* ended, and a wave run again at the same commit applies the rest of a
|
|
7
|
+
* stopped apply under its approval when its plans make only changes that
|
|
8
|
+
* apply did not finish. A wave that plans no change closes a stopped
|
|
9
|
+
* apply; `approvals.spendStanding` spends an approval of the digest a wave
|
|
10
|
+
* its gate let through applies.
|
|
11
|
+
*/
|
|
12
|
+
import { afterAll, describe, expect, test, vi } from "vitest";
|
|
13
|
+
import { OP_WAVES_RESUME_ENV } from "./op-waves-split-resume";
|
|
14
|
+
import { execFileSync } from "node:child_process";
|
|
15
|
+
import { mkdtempSync, realpathSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
|
|
16
|
+
import { tmpdir } from "node:os";
|
|
17
|
+
import { join } from "node:path";
|
|
18
|
+
import { assertOpWavesSpec, opWaveOutcomeDir, type OpWavesSpec } from "./op-waves";
|
|
19
|
+
import { runOpWave, type OpWaveRunPort, type OpWaveShowAtBase } from "./op-waves-run";
|
|
20
|
+
import { opWaveRunRecordFileName } from "./op-waves-split";
|
|
21
|
+
import { memoryGateLedgerPort } from "./gate";
|
|
22
|
+
import { CapabilityRegistry, type Capability } from "../components/capability";
|
|
23
|
+
import { CHANT_EXIT } from "../exit-codes";
|
|
24
|
+
import { NEXT_RELEASE } from "../release-floors";
|
|
25
|
+
import {
|
|
26
|
+
OP_WAVES_REMAINDER_FLOOR,
|
|
27
|
+
OP_WAVES_REMAINDER_PARITY_FLOOR,
|
|
28
|
+
OP_WAVE_REMAINDER_FOLLOWS,
|
|
29
|
+
opWaveApprovedChanges,
|
|
30
|
+
opWaveCoverRemainder,
|
|
31
|
+
opWaveStoppedApply,
|
|
32
|
+
opWaveUnfinishedApply,
|
|
33
|
+
type AppliedGateChange,
|
|
34
|
+
} from "./op-waves-remainder";
|
|
35
|
+
import type { AppliedGateRecord, FinishedGateRecord } from "../lifecycle/gate-applied";
|
|
36
|
+
import { OP_WAVE_COST_MEMBER } from "./op-waves-capability-spec";
|
|
37
|
+
|
|
38
|
+
const dirs: string[] = [];
|
|
39
|
+
afterAll(() => {
|
|
40
|
+
for (const d of dirs) rmSync(d, { recursive: true, force: true });
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
function tmp(prefix: string): string {
|
|
44
|
+
const d = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
|
|
45
|
+
dirs.push(d);
|
|
46
|
+
return d;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function git(cwd: string, ...args: string[]): string {
|
|
50
|
+
return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** A clone of a bare remote, a writer of chant/lifecycle (the resource grain's rows live there). */
|
|
54
|
+
function writer(): string {
|
|
55
|
+
const remote = tmp("remainder-remote-");
|
|
56
|
+
git(remote, "init", "-q", "--bare", "-b", "main");
|
|
57
|
+
const c = tmp("remainder-clone-");
|
|
58
|
+
git(c, "init", "-q", "-b", "main");
|
|
59
|
+
git(c, "config", "user.email", "w@chant.dev");
|
|
60
|
+
git(c, "config", "user.name", "Writer");
|
|
61
|
+
git(c, "config", "commit.gpgsign", "false");
|
|
62
|
+
writeFileSync(join(c, "README.md"), "# t\n");
|
|
63
|
+
git(c, "add", "README.md");
|
|
64
|
+
git(c, "commit", "-q", "-m", "init");
|
|
65
|
+
git(c, "remote", "add", "origin", remote);
|
|
66
|
+
git(c, "push", "-q", "origin", "main");
|
|
67
|
+
return c;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const alive = async () => "alive" as const;
|
|
71
|
+
const HEAD = "c".repeat(40);
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* A root whose engine records each resource as its apply returns (the
|
|
75
|
+
* resource grain): its plan makes the resources not done yet, each with its
|
|
76
|
+
* digest. `stopAfter` has the next apply record that many resources and
|
|
77
|
+
* then fail, as a killed apply leaves its records.
|
|
78
|
+
*/
|
|
79
|
+
function engine() {
|
|
80
|
+
const want: Record<string, string> = { "aws_s3_bucket.a": `sha256:${"a".repeat(64)}`, "aws_s3_bucket.b": `sha256:${"b".repeat(64)}` };
|
|
81
|
+
const done = new Set<string>();
|
|
82
|
+
const ran: string[][] = [];
|
|
83
|
+
const at = { stopAfter: undefined as number | undefined };
|
|
84
|
+
const remaining = (): Record<string, string> => Object.fromEntries(Object.entries(want).filter(([k]) => !done.has(k)));
|
|
85
|
+
const planDigest = (r: Record<string, string>): string => `sha256:${Buffer.from(JSON.stringify(r)).toString("hex").padEnd(64, "0").slice(0, 64)}`;
|
|
86
|
+
const cap: Capability<Record<string, unknown>, unknown> = {
|
|
87
|
+
kind: "fake-cdf",
|
|
88
|
+
async plan(_ctx, input) {
|
|
89
|
+
const root = String(input.root);
|
|
90
|
+
const r = remaining();
|
|
91
|
+
const entries = Object.keys(r).map((address) => ({ member: root, address, type: "aws_s3_bucket", action: "create" }));
|
|
92
|
+
return {
|
|
93
|
+
member: root,
|
|
94
|
+
planDigest: planDigest(r),
|
|
95
|
+
artifact: { root, r },
|
|
96
|
+
resourceDigests: r,
|
|
97
|
+
changeSet: { member: { member: root, lexicon: "terraform", planner: "chant", status: "planned", planDigest: planDigest(r), holes: [] }, entries } as never,
|
|
98
|
+
};
|
|
99
|
+
},
|
|
100
|
+
async run(_ctx, input) {
|
|
101
|
+
const r = Object.keys(remaining());
|
|
102
|
+
const stop = at.stopAfter;
|
|
103
|
+
at.stopAfter = undefined;
|
|
104
|
+
const now: string[] = [];
|
|
105
|
+
for (const [i, address] of r.entries()) {
|
|
106
|
+
if (stop !== undefined && i >= stop) {
|
|
107
|
+
ran.push(now);
|
|
108
|
+
throw new Error(`${String(input.root)}: the apply stopped`);
|
|
109
|
+
}
|
|
110
|
+
done.add(address);
|
|
111
|
+
now.push(address);
|
|
112
|
+
}
|
|
113
|
+
ran.push(now);
|
|
114
|
+
return { applied: input.root };
|
|
115
|
+
},
|
|
116
|
+
defaultLockGrain: () => "resource",
|
|
117
|
+
// On the resource grain with no rows to hold, so the test leases nothing on chant/lifecycle.
|
|
118
|
+
lockRows: () => [],
|
|
119
|
+
};
|
|
120
|
+
return { registry: new CapabilityRegistry().register(cap), want, done, ran, at };
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
const spec = (approvals: Record<string, boolean>, gate: "always" | "never" = "always"): OpWavesSpec => ({
|
|
124
|
+
name: "roots",
|
|
125
|
+
op: "tf-apply",
|
|
126
|
+
step: { kind: "fake-cdf", root: "{target}" },
|
|
127
|
+
approvals,
|
|
128
|
+
waves: [{ name: "dev", runs: [{ target: "network" }], gate }],
|
|
129
|
+
});
|
|
130
|
+
const showOf = (s: OpWavesSpec): OpWaveShowAtBase => () => ({ sha: "b".repeat(40), text: JSON.stringify(s) });
|
|
131
|
+
|
|
132
|
+
let shared: string | undefined;
|
|
133
|
+
|
|
134
|
+
function harness(approvals: Record<string, boolean>, gate: "always" | "never" = "always") {
|
|
135
|
+
const s = spec(approvals, gate);
|
|
136
|
+
const cdf = engine();
|
|
137
|
+
const gates = memoryGateLedgerPort();
|
|
138
|
+
const lines: string[] = [];
|
|
139
|
+
// One writer for the file: each wave lets go of its rows when it ends, and the tests run one at a time.
|
|
140
|
+
shared ??= writer();
|
|
141
|
+
const base = { spec: s, specFile: "waves.json", wave: 1, cwd: shared, show: showOf(s), gates, capabilities: cdf.registry, lockLiveness: alive, releases: false as const, runs: { append: async () => {} } as OpWaveRunPort, head: HEAD, log: (l: string) => void lines.push(l) };
|
|
142
|
+
const approve = async (digest: string) => void (await gates.appendResolution!({ op: "roots", gate: "roots-wave-1", resolvedBy: "alice", timestamp: new Date(Date.now() + 5).toISOString(), planDigest: digest }));
|
|
143
|
+
return { s, cdf, gates, base, lines, approve };
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
describe("the stopped-apply record (#5047)", () => {
|
|
147
|
+
test("the pure rules: changes on the resource grain, the stopped apply at this commit, the rest of it", () => {
|
|
148
|
+
const grains = new Map([["network", { lock: { grain: "resource" } }], ["dns", { lock: { grain: "target" } }]]);
|
|
149
|
+
expect(opWaveApprovedChanges([{ member: "network", resources: { b: "2", a: "1" } }, { member: "dns", empty: true }], grains)).toEqual([
|
|
150
|
+
{ target: "network", address: "a", digest: "1" },
|
|
151
|
+
{ target: "network", address: "b", digest: "2" },
|
|
152
|
+
]);
|
|
153
|
+
// A changing run on another grain, or without resource digests, cannot resume.
|
|
154
|
+
expect(opWaveApprovedChanges([{ member: "dns", resources: { x: "1" } }], grains)).toBeUndefined();
|
|
155
|
+
expect(opWaveApprovedChanges([{ member: "network" }], grains)).toBeUndefined();
|
|
156
|
+
|
|
157
|
+
const approved: AppliedGateChange[] = [{ target: "network", address: "a", digest: "1" }, { target: "network", address: "b", digest: "2" }];
|
|
158
|
+
expect(opWaveCoverRemainder(approved, [approved[1]!])).toEqual({ covered: true, remaining: [approved[1]], done: [approved[0]] });
|
|
159
|
+
expect(opWaveCoverRemainder(approved, [{ ...approved[1]!, digest: "9" }])).toMatchObject({ covered: false, why: "network b is a change the approved plans did not make" });
|
|
160
|
+
expect(opWaveCoverRemainder(approved, [approved[1]!], { now: [{ member: "(cost)", planDigest: "c" }] })).toMatchObject({ covered: false });
|
|
161
|
+
expect(opWaveCoverRemainder(approved, [approved[1]!], { now: [{ member: "(cost)", planDigest: "c" }], approved: [{ member: "(cost)", planDigest: "c" }] })).toMatchObject({ covered: true });
|
|
162
|
+
|
|
163
|
+
const line = (at: string, commit: string, changes?: AppliedGateChange[]): AppliedGateRecord => ({ version: 1, kind: "applied", op: "roots", gate: "g", planDigest: `d-${at}`, approvedAt: "2026-11-01T00:00:00Z", approvedBy: "alice", timestamp: at, commit, ...(changes ? { changes } : {}) });
|
|
164
|
+
const first = line("2026-11-02T00:00:00Z", HEAD, approved);
|
|
165
|
+
const fin = (l: AppliedGateRecord, result: "applied" | "failed"): FinishedGateRecord => ({ version: 1, kind: "finished", op: "roots", gate: "g", planDigest: l.planDigest, applied: l.timestamp, result, timestamp: "2026-11-03T00:00:00Z" });
|
|
166
|
+
expect(opWaveStoppedApply([first], [], "g", HEAD)).toBe(first);
|
|
167
|
+
expect(opWaveStoppedApply([first], [fin(first, "failed")], "g", HEAD)).toBe(first);
|
|
168
|
+
expect(opWaveStoppedApply([first], [fin(first, "applied")], "g", HEAD)).toBeUndefined();
|
|
169
|
+
expect(opWaveStoppedApply([first], [], "g", "d".repeat(40))).toBeUndefined();
|
|
170
|
+
// A newer apply of the gate at another commit leaves nothing to take up.
|
|
171
|
+
expect(opWaveStoppedApply([first, line("2026-11-04T00:00:00Z", "d".repeat(40), approved)], [], "g", HEAD)).toBeUndefined();
|
|
172
|
+
expect(opWaveUnfinishedApply([first], [], "g")).toBe(first);
|
|
173
|
+
expect(opWaveUnfinishedApply([first], [fin(first, "failed")], "g")).toBeUndefined();
|
|
174
|
+
expect(OP_WAVES_REMAINDER_FLOOR).toBe(NEXT_RELEASE);
|
|
175
|
+
});
|
|
176
|
+
|
|
177
|
+
test("#5056: the cost member's digest follows from the plans, so the rest covers it moved; any other extra still has to match", () => {
|
|
178
|
+
const approved: AppliedGateChange[] = [{ target: "network", address: "a", digest: "1" }, { target: "network", address: "b", digest: "2" }];
|
|
179
|
+
const cost = (d: string) => ({ member: OP_WAVE_COST_MEMBER, planDigest: d });
|
|
180
|
+
expect(OP_WAVE_REMAINDER_FOLLOWS).toEqual(["(monthly cost)"]);
|
|
181
|
+
// Part of the wave applied, so the rest costs less: the cost member moved, and every change is an approved one.
|
|
182
|
+
expect(opWaveCoverRemainder(approved, [approved[1]!], { now: [cost("sha256:less")], approved: [cost("sha256:all")] })).toEqual({ covered: true, remaining: [approved[1]], done: [approved[0]] });
|
|
183
|
+
expect(opWaveCoverRemainder(approved, [approved[1]!], { now: [cost("sha256:less")] })).toMatchObject({ covered: true });
|
|
184
|
+
// A change is still compared, and another extra still has to be the approved one.
|
|
185
|
+
expect(opWaveCoverRemainder(approved, [{ ...approved[1]!, digest: "9" }], { now: [cost("sha256:less")], approved: [cost("sha256:all")] })).toMatchObject({ covered: false });
|
|
186
|
+
expect(opWaveCoverRemainder(approved, [approved[1]!], { now: [cost("sha256:less"), { member: "migrate:m1", planDigest: "m" }], approved: [cost("sha256:all")] })).toMatchObject({ covered: false, why: "migrate:m1 is not as the approved set held it" });
|
|
187
|
+
expect(OP_WAVES_REMAINDER_PARITY_FLOOR).toBe(NEXT_RELEASE);
|
|
188
|
+
});
|
|
189
|
+
|
|
190
|
+
test("the spec takes approvals.remainder and approvals.spendStanding beside approvals.spend alone", () => {
|
|
191
|
+
expect(() => assertOpWavesSpec(spec({ spend: true, remainder: true, spendStanding: true }))).not.toThrow();
|
|
192
|
+
expect(() => assertOpWavesSpec(spec({ remainder: true }))).toThrow(/approvals.remainder works on the lines approvals.spend writes/);
|
|
193
|
+
expect(() => assertOpWavesSpec(spec({ spend: true, spendStanding: "yes" } as never))).toThrow(/approvals.spendStanding must be true or false/);
|
|
194
|
+
});
|
|
195
|
+
|
|
196
|
+
test("a wave run again at the same commit applies the rest of its stopped apply under the approval, and says how it ended", async () => {
|
|
197
|
+
const { cdf, gates, base, approve } = harness({ spend: true, remainder: true });
|
|
198
|
+
const waited = await runOpWave(base);
|
|
199
|
+
expect(waited.exitCode).toBe(CHANT_EXIT.waiting);
|
|
200
|
+
await approve(waited.decision!.digest);
|
|
201
|
+
// The apply stops after one of its two resources.
|
|
202
|
+
cdf.at.stopAfter = 1;
|
|
203
|
+
const stopped = await runOpWave(base);
|
|
204
|
+
expect(stopped.exitCode).toBe(CHANT_EXIT.failed);
|
|
205
|
+
expect(gates.applied).toHaveLength(1);
|
|
206
|
+
expect(gates.applied[0]).toMatchObject({
|
|
207
|
+
planDigest: waited.decision!.digest,
|
|
208
|
+
approvedBy: "alice",
|
|
209
|
+
commit: HEAD,
|
|
210
|
+
changes: [
|
|
211
|
+
{ target: "network", address: "aws_s3_bucket.a", digest: cdf.want["aws_s3_bucket.a"] },
|
|
212
|
+
{ target: "network", address: "aws_s3_bucket.b", digest: cdf.want["aws_s3_bucket.b"] },
|
|
213
|
+
],
|
|
214
|
+
});
|
|
215
|
+
expect(gates.finished).toEqual([expect.objectContaining({ planDigest: waited.decision!.digest, applied: gates.applied[0]!.timestamp, result: "failed" })]);
|
|
216
|
+
|
|
217
|
+
const rest = await runOpWave(base);
|
|
218
|
+
expect(rest.exitCode).toBe(0);
|
|
219
|
+
expect(rest.decision).toMatchObject({ status: "approved", approvedBy: "alice", resumes: { planDigest: waited.decision!.digest, appliedAt: gates.applied[0]!.timestamp } });
|
|
220
|
+
expect(rest.decision!.digest).not.toBe(waited.decision!.digest);
|
|
221
|
+
expect(cdf.ran.at(-1)).toEqual(["aws_s3_bucket.b"]);
|
|
222
|
+
// It applied under the stopped apply's line: no applied line of its own, and that line's finished line says applied.
|
|
223
|
+
expect(gates.applied).toHaveLength(1);
|
|
224
|
+
expect(gates.finished.at(-1)).toMatchObject({ planDigest: waited.decision!.digest, applied: gates.applied[0]!.timestamp, result: "applied" });
|
|
225
|
+
// Nothing is left: the wave plans no change and applies nothing again.
|
|
226
|
+
const after = await runOpWave(base);
|
|
227
|
+
expect(after.exitCode).toBe(0);
|
|
228
|
+
expect(gates.finished).toHaveLength(2);
|
|
229
|
+
});
|
|
230
|
+
|
|
231
|
+
test("another commit, or a change the approved plans did not make, waits for an approval of its own", async () => {
|
|
232
|
+
const { cdf, gates, base, approve, lines } = harness({ spend: true, remainder: true });
|
|
233
|
+
const waited = await runOpWave(base);
|
|
234
|
+
await approve(waited.decision!.digest);
|
|
235
|
+
cdf.at.stopAfter = 1;
|
|
236
|
+
await runOpWave(base);
|
|
237
|
+
expect((await runOpWave({ ...base, head: "d".repeat(40) })).exitCode).toBe(CHANT_EXIT.waiting);
|
|
238
|
+
cdf.want["aws_s3_bucket.b"] = `sha256:${"9".repeat(64)}`;
|
|
239
|
+
expect((await runOpWave(base)).exitCode).toBe(CHANT_EXIT.waiting);
|
|
240
|
+
expect(lines.some((l) => l.includes("aws_s3_bucket.b is a change the approved plans did not make, so these plans need an approval of their own"))).toBe(true);
|
|
241
|
+
expect(cdf.ran.at(-1)).toEqual(["aws_s3_bucket.a"]);
|
|
242
|
+
expect(gates.applied).toHaveLength(1);
|
|
243
|
+
});
|
|
244
|
+
|
|
245
|
+
test("without approvals.remainder the applied line names no changes, nothing finishes, and the rest waits", async () => {
|
|
246
|
+
const { cdf, gates, base, approve } = harness({ spend: true });
|
|
247
|
+
const waited = await runOpWave(base);
|
|
248
|
+
await approve(waited.decision!.digest);
|
|
249
|
+
cdf.at.stopAfter = 1;
|
|
250
|
+
await runOpWave(base);
|
|
251
|
+
expect(gates.applied).toHaveLength(1);
|
|
252
|
+
expect(gates.applied[0]).not.toHaveProperty("changes");
|
|
253
|
+
expect(gates.applied[0]).not.toHaveProperty("commit");
|
|
254
|
+
expect(gates.finished).toEqual([]);
|
|
255
|
+
expect((await runOpWave(base)).exitCode).toBe(CHANT_EXIT.waiting);
|
|
256
|
+
});
|
|
257
|
+
|
|
258
|
+
test("a wave that plans no change closes a stopped apply as applied", async () => {
|
|
259
|
+
const { cdf, gates, base, approve } = harness({ spend: true, remainder: true });
|
|
260
|
+
const waited = await runOpWave(base);
|
|
261
|
+
await approve(waited.decision!.digest);
|
|
262
|
+
cdf.at.stopAfter = 1;
|
|
263
|
+
await runOpWave(base);
|
|
264
|
+
// The killed apply wrote no finished line; something else applied the rest.
|
|
265
|
+
gates.finished.length = 0;
|
|
266
|
+
cdf.done.add("aws_s3_bucket.b");
|
|
267
|
+
expect((await runOpWave(base)).exitCode).toBe(0);
|
|
268
|
+
expect(gates.finished).toEqual([expect.objectContaining({ planDigest: waited.decision!.digest, applied: gates.applied[0]!.timestamp, result: "applied" })]);
|
|
269
|
+
});
|
|
270
|
+
|
|
271
|
+
test("approvals.spendStanding: a wave its gate lets through spends the approval of its digest that stands", async () => {
|
|
272
|
+
// The digest the plans give, as an earlier wait's approval names it.
|
|
273
|
+
const digest = (await runOpWave(harness({ spend: true }).base)).decision!.digest;
|
|
274
|
+
const standing = harness({ spend: true, spendStanding: true }, "never");
|
|
275
|
+
await standing.approve(digest);
|
|
276
|
+
expect((await runOpWave(standing.base)).exitCode).toBe(0);
|
|
277
|
+
expect(standing.gates.applied).toEqual([expect.objectContaining({ gate: "roots-wave-1", planDigest: digest, approvedBy: "alice" })]);
|
|
278
|
+
// Off by default.
|
|
279
|
+
const plain = harness({ spend: true }, "never");
|
|
280
|
+
await plain.approve(digest);
|
|
281
|
+
expect((await runOpWave(plain.base)).exitCode).toBe(0);
|
|
282
|
+
expect(plain.gates.applied).toEqual([]);
|
|
283
|
+
});
|
|
284
|
+
|
|
285
|
+
test("a split wave: the gate job records the changes, the record job says how the apply ended, and the applying job run again applies the rest", async () => {
|
|
286
|
+
const { cdf, gates, base, approve } = harness({ spend: true, remainder: true });
|
|
287
|
+
await runOpWave({ ...base, phase: "plan" });
|
|
288
|
+
const waited = await runOpWave({ ...base, phase: "gate" });
|
|
289
|
+
expect(waited.exitCode).toBe(CHANT_EXIT.waiting);
|
|
290
|
+
await approve(waited.decision!.digest);
|
|
291
|
+
await runOpWave({ ...base, phase: "plan" });
|
|
292
|
+
expect((await runOpWave({ ...base, phase: "gate" })).exitCode).toBe(CHANT_EXIT.done);
|
|
293
|
+
expect(gates.applied).toEqual([expect.objectContaining({ commit: HEAD, changes: expect.arrayContaining([expect.objectContaining({ address: "aws_s3_bucket.b" })]) })]);
|
|
294
|
+
// The applying job is killed after one resource: it leaves no run record, and the record job writes no finished line.
|
|
295
|
+
cdf.at.stopAfter = 1;
|
|
296
|
+
await runOpWave({ ...base, phase: "apply" });
|
|
297
|
+
unlinkSync(join(base.cwd, opWaveOutcomeDir(base.spec), opWaveRunRecordFileName(1)));
|
|
298
|
+
expect((await runOpWave({ ...base, phase: "record" })).exitCode).toBe(CHANT_EXIT.failed);
|
|
299
|
+
expect(gates.finished).toEqual([]);
|
|
300
|
+
// GitHub re-runs the failed applying and record jobs: the applying job's plan moved, to the rest of the decision's changes.
|
|
301
|
+
const again = await runOpWave({ ...base, phase: "apply" });
|
|
302
|
+
expect(again).toMatchObject({ exitCode: 0, applied: ["network"], moved: [] });
|
|
303
|
+
expect(cdf.ran.at(-1)).toEqual(["aws_s3_bucket.b"]);
|
|
304
|
+
expect((await runOpWave({ ...base, phase: "record" })).exitCode).toBe(0);
|
|
305
|
+
expect(gates.finished).toEqual([expect.objectContaining({ planDigest: waited.decision!.digest, applied: gates.applied[0]!.timestamp, result: "applied" })]);
|
|
306
|
+
});
|
|
307
|
+
|
|
308
|
+
test("#5052: on GitLab the gate job's line names the applying and record jobs; a new run of the same commit (Forgejo's resume) applies the rest", async () => {
|
|
309
|
+
vi.stubEnv("GITLAB_CI", "true");
|
|
310
|
+
vi.stubEnv("CI_API_V4_URL", "https://gl/api/v4");
|
|
311
|
+
vi.stubEnv("CI_PROJECT_ID", "7");
|
|
312
|
+
vi.stubEnv("CI_PIPELINE_ID", "100");
|
|
313
|
+
vi.stubEnv("CI_JOB_ID", "555");
|
|
314
|
+
vi.stubEnv("CI_JOB_NAME", "wave-1-dev-gate");
|
|
315
|
+
vi.stubEnv(OP_WAVES_RESUME_ENV, JSON.stringify({ apply: ["wave-1-dev"], record: "wave-1-dev-record" }));
|
|
316
|
+
try {
|
|
317
|
+
const { cdf, gates, base, approve } = harness({ spend: true, remainder: true });
|
|
318
|
+
await runOpWave({ ...base, phase: "plan" });
|
|
319
|
+
const waited = await runOpWave({ ...base, phase: "gate" });
|
|
320
|
+
await approve(waited.decision!.digest);
|
|
321
|
+
await runOpWave({ ...base, phase: "plan" });
|
|
322
|
+
expect((await runOpWave({ ...base, phase: "gate" })).exitCode).toBe(CHANT_EXIT.done);
|
|
323
|
+
expect(gates.applied[0]!.resume).toMatchObject({ forge: "gitlab", run: "100", job: "555", retry: { apply: ["wave-1-dev"], record: "wave-1-dev-record" } });
|
|
324
|
+
cdf.at.stopAfter = 1;
|
|
325
|
+
await runOpWave({ ...base, phase: "apply" });
|
|
326
|
+
unlinkSync(join(base.cwd, opWaveOutcomeDir(base.spec), opWaveRunRecordFileName(1)));
|
|
327
|
+
expect((await runOpWave({ ...base, phase: "record" })).exitCode).toBe(CHANT_EXIT.failed);
|
|
328
|
+
// A new run at the same commit, from its plan job: the gate job takes up the stopped apply, and writes no line of its own.
|
|
329
|
+
await runOpWave({ ...base, phase: "plan" });
|
|
330
|
+
const gate = await runOpWave({ ...base, phase: "gate" });
|
|
331
|
+
expect(gate.exitCode).toBe(CHANT_EXIT.done);
|
|
332
|
+
expect(gate.decision?.resumes).toMatchObject({ planDigest: waited.decision!.digest, appliedAt: gates.applied[0]!.timestamp });
|
|
333
|
+
expect(gates.applied).toHaveLength(1);
|
|
334
|
+
expect(await runOpWave({ ...base, phase: "apply" })).toMatchObject({ exitCode: 0, applied: ["network"] });
|
|
335
|
+
expect(cdf.ran.at(-1)).toEqual(["aws_s3_bucket.b"]);
|
|
336
|
+
expect((await runOpWave({ ...base, phase: "record" })).exitCode).toBe(0);
|
|
337
|
+
expect(gates.finished).toEqual([expect.objectContaining({ planDigest: waited.decision!.digest, applied: gates.applied[0]!.timestamp, result: "applied" })]);
|
|
338
|
+
} finally {
|
|
339
|
+
vi.unstubAllEnvs();
|
|
340
|
+
}
|
|
341
|
+
});
|
|
342
|
+
});
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The rest of an apply that stopped, under the approval it applied under
|
|
3
|
+
* (#5047), with the spec's `approvals.remainder` and `approvals.spend`, both
|
|
4
|
+
* read at base.
|
|
5
|
+
*
|
|
6
|
+
* A wave that applies under an approval writes its applied line on
|
|
7
|
+
* `chant/lifecycle` (`_gates/<op>/applied.jsonl`, #3784) first. Under
|
|
8
|
+
* `remainder` that line carries each change the approved plans make: a run's
|
|
9
|
+
* resource, by the engine's address, and the resource's digest (the
|
|
10
|
+
* capability's `resourceDigests`), with the commit and the run (`resume`,
|
|
11
|
+
* which `chant run resume` starts again once it is gone). Only an engine that
|
|
12
|
+
* records each resource as its apply returns (the `resource` lock grain, such
|
|
13
|
+
* as choudoufu's) plans exactly what it did not apply after a stop, so a wave
|
|
14
|
+
* with a changing run on another grain, or with no resource digests, records
|
|
15
|
+
* no changes and never resumes as a remainder. The job that applies the
|
|
16
|
+
* whole wave (a split wave's record job) writes how the apply ended, a
|
|
17
|
+
* `finished` line; a killed apply writes none.
|
|
18
|
+
*
|
|
19
|
+
* Run again at the same commit (the resume re-runs the stopped job), the
|
|
20
|
+
* wave plans what is left. That plan has another digest, so the spent
|
|
21
|
+
* approval would not count. It does when every change the plans make is one
|
|
22
|
+
* the stopped apply's line names, with the same digest: the ones it no longer
|
|
23
|
+
* makes are done, since the config is the same and the engine records each
|
|
24
|
+
* resource it applied. Any other change, a digest member that is no run
|
|
25
|
+
* beyond the approved ones, or another commit, leaves the wave to wait for an
|
|
26
|
+
* approval of its own. The wave then applies under the stopped line, writes
|
|
27
|
+
* no applied line of its own, and writes that line's finished line.
|
|
28
|
+
*
|
|
29
|
+
* A split wave's applying job (#4987) re-plans its runs through the step: a
|
|
30
|
+
* run whose plan moved since the gate job's decision applies when its plan
|
|
31
|
+
* makes only changes the decision recorded, with the same digests.
|
|
32
|
+
*
|
|
33
|
+
* A wave whose plans change nothing closes the newest stopped apply of its
|
|
34
|
+
* gate as applied, since something applied the rest. With
|
|
35
|
+
* `approvals.spendStanding` a wave its gate lets through spends an approval
|
|
36
|
+
* of its digest that stands (`./op-waves-run.ts`).
|
|
37
|
+
*
|
|
38
|
+
* Pure: no git, no ledger, no clock.
|
|
39
|
+
*/
|
|
40
|
+
|
|
41
|
+
import type { AppliedGateChange, AppliedGateRecord, FinishedGateRecord } from "../lifecycle/gate-applied";
|
|
42
|
+
import { finishedApply } from "../lifecycle/gate-applied";
|
|
43
|
+
import { samePlanDigest } from "../lifecycle/plan-digest";
|
|
44
|
+
import { OP_WAVE_COST_MEMBER } from "./op-waves-capability-spec";
|
|
45
|
+
|
|
46
|
+
export type { AppliedGateChange } from "../lifecycle/gate-applied";
|
|
47
|
+
|
|
48
|
+
export { OP_WAVES_REMAINDER_FLOOR, OP_WAVES_REMAINDER_PARITY_FLOOR } from "../release-floors";
|
|
49
|
+
|
|
50
|
+
/** A planned run, as the remainder reads it: its member, whether its plan is empty, and its resources' digests. */
|
|
51
|
+
export interface OpWaveRemainderMember {
|
|
52
|
+
member: string;
|
|
53
|
+
empty?: boolean;
|
|
54
|
+
resources?: Record<string, string>;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** The lock grain of each run's step plan, by target. */
|
|
58
|
+
export type OpWaveRemainderGrains = ReadonlyMap<string, { lock?: { grain: string } }> | undefined;
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Every change the plans make, sorted by target and address, or undefined
|
|
62
|
+
* when a run that changes something did not plan through the step on the
|
|
63
|
+
* `resource` grain or gave no resource digests: the wave cannot resume as a
|
|
64
|
+
* remainder.
|
|
65
|
+
*/
|
|
66
|
+
export function opWaveApprovedChanges(members: readonly OpWaveRemainderMember[], grains: OpWaveRemainderGrains): AppliedGateChange[] | undefined {
|
|
67
|
+
const out: AppliedGateChange[] = [];
|
|
68
|
+
for (const m of members) {
|
|
69
|
+
if (m.empty === true) continue;
|
|
70
|
+
if (grains?.get(m.member)?.lock?.grain !== "resource" || m.resources === undefined) return undefined;
|
|
71
|
+
for (const [address, digest] of Object.entries(m.resources)) out.push({ target: m.member, address, digest });
|
|
72
|
+
}
|
|
73
|
+
return out.sort((a, b) => (a.target === b.target ? (a.address < b.address ? -1 : a.address > b.address ? 1 : 0) : a.target < b.target ? -1 : 1));
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const time = (iso: string): number => new Date(iso).getTime();
|
|
77
|
+
|
|
78
|
+
/** The newest applied line of `gate`, oldest wins a tie by order. */
|
|
79
|
+
function newestLine(applied: readonly AppliedGateRecord[], gate: string): AppliedGateRecord | undefined {
|
|
80
|
+
return applied.filter((a) => a.gate === gate).reduce<AppliedGateRecord | undefined>((n, a) => (!n || time(a.timestamp) >= time(n.timestamp) ? a : n), undefined);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* The apply of `gate` a wave at `commit` takes up: the gate's newest applied
|
|
85
|
+
* line, when it names changes, was written at `commit`, and no finished line
|
|
86
|
+
* says it applied. Undefined when there is none.
|
|
87
|
+
*/
|
|
88
|
+
export function opWaveStoppedApply(applied: readonly AppliedGateRecord[], finished: readonly FinishedGateRecord[], gate: string, commit: string | undefined): AppliedGateRecord | undefined {
|
|
89
|
+
const line = newestLine(applied, gate);
|
|
90
|
+
if (!line?.changes || commit === undefined || line.commit !== commit) return undefined;
|
|
91
|
+
return finishedApply(finished, line)?.result === "applied" ? undefined : line;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** The newest applied line of `gate` that names changes and has no finished line at all: what a wave that changes nothing closes. */
|
|
95
|
+
export function opWaveUnfinishedApply(applied: readonly AppliedGateRecord[], finished: readonly FinishedGateRecord[], gate: string): AppliedGateRecord | undefined {
|
|
96
|
+
const line = newestLine(applied, gate);
|
|
97
|
+
return line?.changes && !finishedApply(finished, line) ? line : undefined;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** Whether the plans now are the rest of the approved changes. */
|
|
101
|
+
export type OpWaveCover =
|
|
102
|
+
| { covered: true; remaining: AppliedGateChange[]; done: AppliedGateChange[] }
|
|
103
|
+
| { covered: false; why: string };
|
|
104
|
+
|
|
105
|
+
const key = (c: Pick<AppliedGateChange, "target" | "address">): string => `${c.target} ${c.address}`;
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* The digest members that are no run whose digest follows from the plans
|
|
109
|
+
* (#5056): the cost member, `(monthly cost)`, chant's `holds.cost` and
|
|
110
|
+
* terragucci's alike, which digests the wave's monthly change. Part of the
|
|
111
|
+
* wave applied, so the rest costs less and the digest moves; every change is
|
|
112
|
+
* still compared, so the cover leaves it out on both sides.
|
|
113
|
+
*/
|
|
114
|
+
export const OP_WAVE_REMAINDER_FOLLOWS: readonly string[] = [OP_WAVE_COST_MEMBER];
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Whether `now`, the changes the plans make, are the rest of `approved`:
|
|
118
|
+
* each one approved with the same digest. The approved ones it no longer
|
|
119
|
+
* makes are done. `extras` are the digest members that are no run, now and
|
|
120
|
+
* as approved: each one now must be approved with the same digest, except
|
|
121
|
+
* the ones whose digest follows from the plans ({@link OP_WAVE_REMAINDER_FOLLOWS}).
|
|
122
|
+
*/
|
|
123
|
+
export function opWaveCoverRemainder(
|
|
124
|
+
approved: readonly AppliedGateChange[],
|
|
125
|
+
now: readonly AppliedGateChange[] | undefined,
|
|
126
|
+
extras: { now?: readonly { member: string; planDigest: string }[]; approved?: readonly { member: string; planDigest: string }[] } = {},
|
|
127
|
+
): OpWaveCover {
|
|
128
|
+
if (!now) return { covered: false, why: "a run that changes something plans on no resource grain, or gave no resource digests" };
|
|
129
|
+
const was = new Map(approved.map((c) => [key(c), c]));
|
|
130
|
+
const moved = now.filter((c) => was.get(key(c))?.digest !== c.digest).map(key);
|
|
131
|
+
if (moved.length > 0) return { covered: false, why: `${moved.join(", ")} ${moved.length === 1 ? "is a change" : "are changes"} the approved plans did not make` };
|
|
132
|
+
const extra = (extras.now ?? []).filter((e) => !OP_WAVE_REMAINDER_FOLLOWS.includes(e.member) && !(extras.approved ?? []).some((a) => a.member === e.member && samePlanDigest(a.planDigest, e.planDigest))).map((e) => e.member);
|
|
133
|
+
if (extra.length > 0) return { covered: false, why: `${extra.join(", ")} ${extra.length === 1 ? "is" : "are"} not as the approved set held ${extra.length === 1 ? "it" : "them"}` };
|
|
134
|
+
const planned = new Set(now.map(key));
|
|
135
|
+
return { covered: true, remaining: [...now], done: approved.filter((c) => !planned.has(key(c))) };
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* A run's plan in a split wave's applying job, against the changes the gate
|
|
140
|
+
* job's decision recorded (#5047): covered when it makes only changes of
|
|
141
|
+
* that run the decision holds, with the same digests.
|
|
142
|
+
*/
|
|
143
|
+
export function opWaveRunCovered(approved: readonly AppliedGateChange[], target: string, plan: OpWaveRemainderMember, grains: OpWaveRemainderGrains): OpWaveCover {
|
|
144
|
+
const now = opWaveApprovedChanges([plan], grains);
|
|
145
|
+
return opWaveCoverRemainder(approved.filter((c) => c.target === target), now?.map((c) => ({ ...c, target })));
|
|
146
|
+
}
|