@intentius/chant 0.124.56 → 0.124.57

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.
Files changed (93) hide show
  1. package/dist/ci-audit/index.d.ts.map +1 -1
  2. package/dist/ci-audit/index.js +1 -2
  3. package/dist/ci-product.d.ts.map +1 -1
  4. package/dist/ci-product.js +4 -5
  5. package/dist/cli/handlers/lifecycle.d.ts.map +1 -1
  6. package/dist/cli/handlers/lifecycle.js +14 -0
  7. package/dist/cli/handlers/pr.d.ts.map +1 -1
  8. package/dist/cli/handlers/pr.js +90 -35
  9. package/dist/components/auto-release.d.ts +5 -2
  10. package/dist/components/auto-release.d.ts.map +1 -1
  11. package/dist/components/auto-release.js +9 -4
  12. package/dist/components/capability.d.ts +10 -0
  13. package/dist/components/capability.d.ts.map +1 -1
  14. package/dist/components/deploy-units.d.ts +12 -0
  15. package/dist/components/deploy-units.d.ts.map +1 -1
  16. package/dist/components/deploy-units.js +20 -1
  17. package/dist/components/pr-pipeline.d.ts +8 -2
  18. package/dist/components/pr-pipeline.d.ts.map +1 -1
  19. package/dist/components/pr-pipeline.js +11 -3
  20. package/dist/components/row-lease.d.ts +22 -1
  21. package/dist/components/row-lease.d.ts.map +1 -1
  22. package/dist/components/row-lease.js +32 -6
  23. package/dist/e2e-harness/index.d.ts.map +1 -1
  24. package/dist/e2e-harness/index.js +1 -2
  25. package/dist/lexicon.d.ts +9 -0
  26. package/dist/lexicon.d.ts.map +1 -1
  27. package/dist/lifecycle/git.d.ts +39 -3
  28. package/dist/lifecycle/git.d.ts.map +1 -1
  29. package/dist/lifecycle/git.js +223 -15
  30. package/dist/lifecycle/lock-rows.d.ts +23 -0
  31. package/dist/lifecycle/lock-rows.d.ts.map +1 -1
  32. package/dist/lifecycle/lock-rows.js +47 -8
  33. package/dist/lifecycle/resource-lock.d.ts +70 -0
  34. package/dist/lifecycle/resource-lock.d.ts.map +1 -1
  35. package/dist/lifecycle/resource-lock.js +241 -5
  36. package/dist/op/gate.js +21 -4
  37. package/dist/op/op-waves-release-port.js +1 -1
  38. package/dist/op/op-waves-release.d.ts +2 -1
  39. package/dist/op/op-waves-release.d.ts.map +1 -1
  40. package/dist/op/op-waves-run.d.ts +8 -0
  41. package/dist/op/op-waves-run.d.ts.map +1 -1
  42. package/dist/op/op-waves-run.js +101 -29
  43. package/dist/op/op-waves.d.ts +18 -0
  44. package/dist/op/op-waves.d.ts.map +1 -1
  45. package/dist/op/op-waves.js +16 -0
  46. package/dist/pr-loop.d.ts.map +1 -1
  47. package/dist/pr-loop.js +1 -2
  48. package/dist/release-floors.d.ts +1 -1
  49. package/dist/release-floors.js +1 -1
  50. package/dist/wave-runtime.mjs +310 -300
  51. package/package.json +1 -1
  52. package/src/ci-audit/index.ts +1 -2
  53. package/src/ci-product.ts +4 -5
  54. package/src/cli/handlers/lifecycle.ts +13 -0
  55. package/src/cli/handlers/pr-before-merge.test.ts +1 -1
  56. package/src/cli/handlers/pr-deploy-inputs.test.ts +1 -1
  57. package/src/cli/handlers/pr-endpoint.test.ts +1 -1
  58. package/src/cli/handlers/pr-green.test.ts +1 -1
  59. package/src/cli/handlers/pr-plan-comment-targets.test.ts +1 -1
  60. package/src/cli/handlers/pr-plan-flags.test.ts +1 -1
  61. package/src/cli/handlers/pr-plan-targets.test.ts +1 -1
  62. package/src/cli/handlers/pr-record.test.ts +34 -2
  63. package/src/cli/handlers/pr-waves-blocked.test.ts +1 -1
  64. package/src/cli/handlers/pr-waves.test.ts +1 -1
  65. package/src/cli/handlers/pr.test.ts +1 -1
  66. package/src/cli/handlers/pr.ts +86 -31
  67. package/src/components/auto-release.test.ts +4 -2
  68. package/src/components/auto-release.ts +9 -5
  69. package/src/components/capability.ts +10 -0
  70. package/src/components/deploy-units.test.ts +18 -1
  71. package/src/components/deploy-units.ts +26 -1
  72. package/src/components/pr-pipeline.ts +12 -3
  73. package/src/components/row-lease.test.ts +61 -1
  74. package/src/components/row-lease.ts +48 -7
  75. package/src/e2e-harness/index.ts +1 -2
  76. package/src/lexicon.ts +9 -0
  77. package/src/lifecycle/git.test.ts +155 -0
  78. package/src/lifecycle/git.ts +213 -17
  79. package/src/lifecycle/lock-rows.test.ts +6 -1
  80. package/src/lifecycle/lock-rows.ts +58 -7
  81. package/src/lifecycle/resource-lock-wait.test.ts +292 -0
  82. package/src/lifecycle/resource-lock.ts +261 -7
  83. package/src/op/gate.test.ts +7 -5
  84. package/src/op/gate.ts +20 -4
  85. package/src/op/op-waves-after-plan.test.ts +1 -2
  86. package/src/op/op-waves-ledger-lock.test.ts +208 -0
  87. package/src/op/op-waves-release-port.ts +1 -1
  88. package/src/op/op-waves-release.ts +1 -1
  89. package/src/op/op-waves-run.ts +104 -29
  90. package/src/op/op-waves.ts +18 -0
  91. package/src/pr-loop-bundle.test.ts +0 -2
  92. package/src/pr-loop.ts +1 -2
  93. package/src/release-floors.ts +1 -1
@@ -34,6 +34,22 @@ export interface DeployUnitRule {
34
34
  field: string;
35
35
  /** The lexicon whose `describeStackStatus` reads this kind of unit. */
36
36
  lexicon: string;
37
+ /**
38
+ * The unit from the whole step, when `field` alone does not name it
39
+ * uniquely. Undefined skips the step, as a missing `field` does.
40
+ */
41
+ unitOf?: (step: Record<string, unknown>) => string | undefined;
42
+ }
43
+
44
+ /**
45
+ * A Pulumi stack's unit: `<dir>/<stack>`, or `<stack>` for a project at the
46
+ * project root. `dir` is where `Pulumi.yaml` is, relative to the project root,
47
+ * so two projects with a `dev` stack are two units. The pulumi lexicon's
48
+ * `changedUnits` answers with the same names.
49
+ */
50
+ export function pulumiStackUnit(dir: string, stack: string): string {
51
+ const d = dir.replace(/\\/g, "/").replace(/^(\.\/)+/, "").replace(/\/+$/, "");
52
+ return d === "" || d === "." ? stack : `${d}/${stack}`;
37
53
  }
38
54
 
39
55
  /**
@@ -68,6 +84,15 @@ export const DEPLOY_UNIT_RULES: readonly DeployUnitRule[] = [
68
84
  // change signal naming the member puts the component in the change. No
69
85
  // lexicon observes it: the member's own pipeline reports its status.
70
86
  { kind: "member-outputs", field: "member", lexicon: "workspace" },
87
+ // A Pulumi stack (plywood#22). Its unit is the stack qualified by the
88
+ // project's directory (`pulumiStackUnit`), which the pulumi lexicon's
89
+ // `changedUnits` names for a changed stack config or program file.
90
+ {
91
+ kind: "pulumi-up",
92
+ field: "stack",
93
+ lexicon: "pulumi",
94
+ unitOf: (s) => (typeof s.stack === "string" && s.stack !== "" ? pulumiStackUnit(typeof s.dir === "string" ? s.dir : ".", s.stack) : undefined),
95
+ },
71
96
  ];
72
97
 
73
98
  /** One resolved unit a component's deploy composition targets. */
@@ -99,7 +124,7 @@ export function deployUnits(deploy: readonly UnitBearingPhase[]): DeployUnit[] {
99
124
  const s = step as { kind?: string } & Record<string, unknown>;
100
125
  const rule = s.kind ? byKind.get(s.kind) : undefined;
101
126
  if (!rule) continue;
102
- const unit = s[rule.field];
127
+ const unit = rule.unitOf ? rule.unitOf(s) : s[rule.field];
103
128
  if (typeof unit !== "string" || unit.length === 0) continue;
104
129
  const key = `${rule.lexicon}\0${unit}`;
105
130
  if (seen.has(key)) continue;
@@ -442,14 +442,23 @@ export function prLoopPassedEnv(forge: ForgeKind, options: Pick<PrLoopPipelineOp
442
442
  export const PR_LOCK_JOB = "lock";
443
443
  export const PR_UNLOCK_JOB = "unlock";
444
444
 
445
- /** `chant lock --from-report` for the plan's report in {@link PR_LOOP_REPORT_DIR}; reads `PR_NUMBER` and `HEAD_SHA`. */
446
- export function prLockCommand(forge: ForgeKind): string {
447
- return ["chant", "lock", "--from-report", `${PR_LOOP_REPORT_DIR}/pr-plan.json`, "--pr", '"$PR_NUMBER"', "--head", '"$HEAD_SHA"', "--stage", "plan", "--forge", forge].join(" ");
445
+ /**
446
+ * `chant lock --from-report` for the plan's report in {@link PR_LOOP_REPORT_DIR}; reads `PR_NUMBER` and `HEAD_SHA`.
447
+ * With a product's `bin` (its words), the line runs through it, as the comment lock jobs do
448
+ * (INTENTIUS/plywood#22): a product's job image need not carry `chant` on PATH.
449
+ */
450
+ export function prLockCommand(forge: ForgeKind, bin?: string): string {
451
+ return withProductBin(["chant", "lock", "--from-report", `${PR_LOOP_REPORT_DIR}/pr-plan.json`, "--pr", '"$PR_NUMBER"', "--head", '"$HEAD_SHA"', "--stage", "plan", "--forge", forge].join(" "), bin);
448
452
  }
449
453
 
450
454
  /** `chant unlock` for the pull request that closed; reads `PR_NUMBER`. */
451
455
  export const PR_UNLOCK_COMMAND = 'chant unlock --pr "$PR_NUMBER"';
452
456
 
457
+ /** {@link PR_UNLOCK_COMMAND} through a product's `bin`, as {@link prLockCommand} takes it. */
458
+ export function prUnlockCommand(bin?: string): string {
459
+ return withProductBin(PR_UNLOCK_COMMAND, bin);
460
+ }
461
+
453
462
  /** The job answering `/<product> lock` (#4588). */
454
463
  export const PR_COMMENT_LOCK_JOB = "comment-lock";
455
464
  /** The job answering `/<product> unlock` (#4588). */
@@ -20,7 +20,7 @@ import { planFanOut } from "./fan-out";
20
20
  import { runFanOut } from "./fan-out-run";
21
21
  import { componentSetFanOut, groupFanOut, planAndRunComponentGroup, planComponentGroup, runComponentGroup } from "./groups";
22
22
  import { applyPrSet, approvalOf, decidePrGate, planPrSet, readOnlyLedger, type PrPlanSet } from "./pr-run";
23
- import { ledgerRowLease, leaseCapabilityStep, LockRowsHeldError, isLockRowsHeldError, type RowLeasePort } from "./row-lease";
23
+ import { ledgerRowLease, leaseCapabilityStep, LockRowsHeldError, LockWaitTimeoutError, isLockRowsHeldError, type RowLeasePort } from "./row-lease";
24
24
  import { memoryGateLedgerPort } from "../op/gate";
25
25
  import { computePlanDigest } from "../lifecycle/plan-digest";
26
26
  import { lockGrainBeforePlan, type LockGrain, type LockRow } from "../lifecycle/lock-rows";
@@ -487,4 +487,64 @@ describe("the ledger port", () => {
487
487
  expect(isLockRowsHeldError(err)).toBe(true);
488
488
  expect((err as Error).message).toContain("run 200 (https://forge.example/runs/200)");
489
489
  });
490
+
491
+ test("a waiting take that reaches its deadline throws LockWaitTimeoutError, still a held error, and leaves the queue", async () => {
492
+ const cwd = repo();
493
+ const other = ledgerRowLease("pr-apply", { cwd, holder: { run: "400", at: NOW }, alive: async () => "alive", log: quiet });
494
+ await other.take([row("stack shop/staging")], "staging");
495
+ const mine = ledgerRowLease("pr-apply", { cwd, holder: { run: "500", at: NOW }, alive: async () => "alive", log: quiet, waitSeconds: 0, pollMs: 1 });
496
+ const err = await mine.take([row("stack shop/staging")], "staging", { wait: true }).catch((e: unknown) => e);
497
+ expect(err).toBeInstanceOf(LockWaitTimeoutError);
498
+ expect(isLockRowsHeldError(err)).toBe(true);
499
+ expect((err as Error).message).toMatch(/^staging: LockWaitTimeoutError: waited \d+s for stack shop\/staging of pr-apply/);
500
+ expect((await readLockRows("pr-apply", { cwd })).waiting).toBeUndefined();
501
+ });
502
+ });
503
+
504
+ describe("the ruling for ci-products (2026-10-28): a step on the target or repo grain waits for its row", () => {
505
+ /** A capability on `grain` whose lexicon names the target's row. */
506
+ function targetCap(grain: LockGrain) {
507
+ const registry = new CapabilityRegistry().register({
508
+ kind: "fake-target",
509
+ defaultLockGrain: () => grain,
510
+ targetLockRow: (input: RootInput) => ({ key: `root ${input.root}`, target: input.root, address: input.root }),
511
+ async plan(_ctx: DeployContext, input: RootInput) {
512
+ return { member: input.root, planDigest: "sha256:" + "1".repeat(64) };
513
+ },
514
+ async run() {
515
+ return {};
516
+ },
517
+ } as never);
518
+ return registry.resolve("fake-target");
519
+ }
520
+ function waitingPort() {
521
+ const takes: Array<{ label: string; keys: string[]; wait: boolean }> = [];
522
+ const port: RowLeasePort = {
523
+ async take(rows, label, opts) {
524
+ takes.push({ label, keys: rows.map((r) => r.key), wait: opts?.wait === true });
525
+ return { release: async () => true };
526
+ },
527
+ };
528
+ return { port, takes };
529
+ }
530
+
531
+ test("the target grain takes the root row with a wait, before anything plans", async () => {
532
+ const { port, takes } = waitingPort();
533
+ const leased = await leaseCapabilityStep(targetCap("target"), { env: "prod", component: "net", rowLease: port }, { root: "net" });
534
+ expect(takes).toEqual([{ label: "net", keys: ["root net"], wait: true }]);
535
+ expect(leased.ctx.plans).toBeUndefined();
536
+ });
537
+
538
+ test("the repo grain waits for the repo row", async () => {
539
+ const { port, takes } = waitingPort();
540
+ await leaseCapabilityStep(targetCap("repo"), { env: "prod", component: "net", rowLease: port }, { root: "net" });
541
+ expect(takes).toEqual([{ label: "net", keys: ["repo"], wait: true }]);
542
+ });
543
+
544
+ test("the resource grain takes its rows with no wait, as before", async () => {
545
+ const w = world();
546
+ const { port, takes } = waitingPort();
547
+ await leaseCapabilityStep(w.registry.resolve("fake-res"), { env: "prod", component: "net", rowLease: port, lockGrain: "resource" }, { root: "net" });
548
+ expect(takes).toEqual([{ label: "net", keys: ["row net"], wait: false }]);
549
+ });
490
550
  });
@@ -15,6 +15,13 @@
15
15
  * - A held row fails the step, or every member of the group, with a record
16
16
  * marked `held`, so the command exits 5 (`CHANT_EXIT.held`) and nothing of
17
17
  * that step applied.
18
+ * - A step on the `target` grain whose lexicon names its target's row
19
+ * (`targetLockRow`: a stock Pulumi stack, a Terraform root), or on the
20
+ * `repo` grain, waits for that row in the ledger's queue, oldest commit
21
+ * first, up to `CHANT_LOCK_WAIT` seconds (ruling for ci-products
22
+ * 2026-10-28, "Ledger lock"), and at the deadline fails with
23
+ * {@link LockWaitTimeoutError}, held, exit 5. A step on the resource grain
24
+ * never waits.
18
25
  *
19
26
  * The port ({@link ledgerRowLease}) writes `_locks/rows/<gate>.json` through
20
27
  * ../lifecycle/resource-lock.ts with one holder for the whole run, and
@@ -22,7 +29,7 @@
22
29
  * change one object let go of its row only once both have ended.
23
30
  */
24
31
  import type { LockGrain, LockRow } from "../lifecycle/lock-rows";
25
- import { lockGrainBeforePlan, resolvePlannedLock, sortedLockRows } from "../lifecycle/lock-rows";
32
+ import { lockGrainBeforePlan, queueRowsOf, resolvePlannedLock, sortedLockRows } from "../lifecycle/lock-rows";
26
33
  import type { LockLiveness, LockRowHolder } from "../lifecycle/resource-lock";
27
34
  import type { Capability, CapabilityPlan, DeployContext } from "./capability";
28
35
 
@@ -38,8 +45,10 @@ export interface RowLeasePort {
38
45
  * Lease `rows` for `label` (a component, or a group's components), all or
39
46
  * nothing. Throws {@link LockRowsHeldError} when another live run holds
40
47
  * one, and any other error when the rows file cannot be read or written.
48
+ * With `wait`, waits in the queue for them instead, and throws
49
+ * {@link LockWaitTimeoutError} at the deadline.
41
50
  */
42
- take(rows: readonly LockRow[], label: string): Promise<RowLease>;
51
+ take(rows: readonly LockRow[], label: string, opts?: { wait?: boolean }): Promise<RowLease>;
43
52
  }
44
53
 
45
54
  /** Another live run holds a row this apply changes (#4594), so nothing of it applied. Exit 5. */
@@ -51,6 +60,14 @@ export class LockRowsHeldError extends Error {
51
60
  }
52
61
  }
53
62
 
63
+ /** A wait for a target's row reached its deadline (ruling for ci-products 2026-10-28): nothing of the step applied. Exit 5, as a held row is. */
64
+ export class LockWaitTimeoutError extends LockRowsHeldError {
65
+ constructor(message: string) {
66
+ super(message);
67
+ this.name = "LockWaitTimeoutError";
68
+ }
69
+ }
70
+
54
71
  /** Whether `err` is a held row ({@link LockRowsHeldError}), by its mark, so a copy from another bundle counts too. */
55
72
  export function isLockRowsHeldError(err: unknown): err is LockRowsHeldError {
56
73
  return typeof err === "object" && err !== null && (err as { lockRowsHeld?: unknown }).lockRowsHeld === true;
@@ -66,6 +83,12 @@ export interface LedgerRowLeaseOptions {
66
83
  holder?: LockRowHolder;
67
84
  /** Where the lease's info lines go. Default stderr. */
68
85
  log?: (line: string) => void;
86
+ /** How long a waiting take waits, in seconds. Default `CHANT_LOCK_WAIT`. */
87
+ waitSeconds?: number;
88
+ /** How often a waiting take reads the rows file again, in ms. Default `CHANT_LOCK_POLL` seconds, else 10 s. */
89
+ pollMs?: number;
90
+ /** The commit time that orders this run in the queue. Default: HEAD's in `cwd`. */
91
+ commitAt?: string;
69
92
  }
70
93
 
71
94
  /**
@@ -80,14 +103,26 @@ export function ledgerRowLease(gate: string, opts: LedgerRowLeaseOptions = {}):
80
103
  let holder: LockRowHolder | undefined = opts.holder;
81
104
  const lock = () => import("../lifecycle/resource-lock");
82
105
  return {
83
- async take(rows, label) {
106
+ async take(rows, label, takeOpts) {
84
107
  const wanted = sortedLockRows(rows);
85
108
  if (wanted.length === 0) return NO_LEASE;
86
- const { leaseLockRows, lockRowHolder, releaseLockRows } = await lock();
109
+ const { commitTimeOf, leaseLockRows, lockPollMs, lockRowHolder, lockWaitSeconds, releaseLockRows } = await lock();
87
110
  holder ??= lockRowHolder(process.env);
88
111
  const fresh = wanted.filter((r) => (counts.get(r.key) ?? 0) === 0);
89
112
  if (fresh.length > 0) {
90
- const leased = await leaseLockRows(gate, fresh, { holder, ...(opts.cwd ? { cwd: opts.cwd } : {}), ...(opts.alive ? { alive: opts.alive } : {}) });
113
+ const commitAt = takeOpts?.wait ? (opts.commitAt ?? (await commitTimeOf(holder.sha ?? "HEAD", opts.cwd))) : undefined;
114
+ const wait = takeOpts?.wait
115
+ ? {
116
+ wait: {
117
+ deadline: Date.now() + (opts.waitSeconds ?? lockWaitSeconds(process.env)) * 1000,
118
+ pollMs: opts.pollMs ?? lockPollMs(process.env),
119
+ log: (line: string) => log(`${label}: ${line}`),
120
+ ...(commitAt ? { commitAt } : {}),
121
+ },
122
+ }
123
+ : {};
124
+ const leased = await leaseLockRows(gate, fresh, { holder, ...(opts.cwd ? { cwd: opts.cwd } : {}), ...(opts.alive ? { alive: opts.alive } : {}), ...wait });
125
+ if (!leased.ok && leased.timedOut) throw new LockWaitTimeoutError(`${label}: LockWaitTimeoutError: ${leased.message}, so nothing of it was applied.`);
91
126
  if (!leased.ok) {
92
127
  throw new LockRowsHeldError(
93
128
  `${label}: ${leased.message}, so nothing of it was applied. Apply again once that run ends; a run that is gone, or whose lease is older than CHANT_LOCK_STALE seconds, is taken over.`,
@@ -136,8 +171,14 @@ export async function leaseCapabilityStep(
136
171
  input: unknown,
137
172
  ): Promise<{ ctx: DeployContext; lease: RowLease }> {
138
173
  const port = ctx.rowLease;
139
- if (!port || ctx.plans !== undefined || !capability.plan) return { ctx, lease: NO_LEASE };
140
- if ((await lockGrainBeforePlan(capability, input, ctx.lockGrain)) !== "resource") return { ctx, lease: NO_LEASE };
174
+ if (!port) return { ctx, lease: NO_LEASE };
175
+ const grain = await lockGrainBeforePlan(capability, input, ctx.lockGrain);
176
+ if (grain !== "resource") {
177
+ // The ruling for ci-products (2026-10-28): the target's row (or the repo row), waited for, whether or not a plan was handed in.
178
+ const queue = await queueRowsOf(capability, input, ctx.component, grain);
179
+ return { ctx, lease: queue.length > 0 ? await port.take(queue, ctx.component, { wait: true }) : NO_LEASE };
180
+ }
181
+ if (ctx.plans !== undefined || !capability.plan) return { ctx, lease: NO_LEASE };
141
182
  const planned: CapabilityPlan = await capability.plan(ctx, input as never);
142
183
  const lock = await resolvePlannedLock(capability, input, planned, ctx.lockGrain);
143
184
  const plans = planned.artifact !== undefined ? { [planned.member]: planned.artifact } : undefined;
@@ -17,10 +17,9 @@
17
17
  */
18
18
  import { existsSync } from "node:fs";
19
19
  import { join } from "node:path";
20
- import { NEXT_RELEASE } from "../release-floors";
21
20
 
22
21
  /** The first chant with the e2e harness. */
23
- export const E2E_HARNESS_FLOOR = NEXT_RELEASE;
22
+ export const E2E_HARNESS_FLOOR = "0.124.56";
24
23
 
25
24
  /**
26
25
  * The harness's chant docker-lexicon project, to `chant build <dir>/src
package/src/lexicon.ts CHANGED
@@ -1049,6 +1049,15 @@ export interface OpWavesPipelineOptions
1049
1049
  * fills it from the active product words. Absent: chant's.
1050
1050
  */
1051
1051
  words?: import("./ci-product-words").CiProductWordsInput | import("./ci-product-words").CiProductWords;
1052
+ /**
1053
+ * Each wave job's timeout in minutes (ruling for ci-products 2026-10-28,
1054
+ * "Ledger lock"). The jobs carry it (`timeout-minutes`, GitLab's
1055
+ * `timeout`), and `CHANT_LOCK_WAIT` five minutes under it, so a run on
1056
+ * the `target` or `repo` grain waiting for its row on the ledger gives up
1057
+ * by name before the forge stops the job. Default
1058
+ * `OP_WAVE_JOB_TIMEOUT_MINUTES` (180).
1059
+ */
1060
+ jobTimeoutMinutes?: number;
1052
1061
  }
1053
1062
 
1054
1063
  /** An Op waves pipeline: one file, and its jobs in order. */
@@ -13,6 +13,9 @@ import {
13
13
  getHeadCommit,
14
14
  pushLifecycle,
15
15
  pushLifecycleReport,
16
+ pushLifecycleRebasing,
17
+ LifecyclePushLostError,
18
+ LIFECYCLE_PUSH_TRIES,
16
19
  StaleLifecycleBranchError,
17
20
  appendReleaseRecordLine,
18
21
  readReleaseLedgerLines,
@@ -30,6 +33,8 @@ import {
30
33
  fetchRefInto,
31
34
  RefCASConflictError,
32
35
  StaleLockError,
36
+ fetchLifecycleStatus,
37
+ requireLifecycleLedger,
33
38
  } from "./git";
34
39
  import { LIFECYCLE_LOCAL_NOTE } from "./local-note";
35
40
 
@@ -526,6 +531,156 @@ describe("lifecycle/git", () => {
526
531
  expect(err.message).toContain("moved");
527
532
  });
528
533
 
534
+ // #4551: a pr handler's push (the merge record pr-record writes) fetches, replays and pushes again, as publishRef does.
535
+ describe("pushLifecycleRebasing", () => {
536
+ /** A, and B with its own copy of the branch: the record job's checkout, taken before A pushes again. */
537
+ async function twoWriters(): Promise<{ a: string; b: string; remotePath: string; done: () => Promise<void> }> {
538
+ const { clonePath: a, remotePath, cleanup } = await setupClonePair();
539
+ const b = join(tmpdir(), `chant-state-clone-b-${Date.now()}-${Math.random()}`);
540
+ git(["clone", "-q", remotePath, b], tmpdir());
541
+ git(["config", "user.email", "record@chant.dev"], b);
542
+ git(["config", "user.name", "Record"], b);
543
+ await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: a });
544
+ expect(await pushLifecycle({ cwd: a })).toBe(true);
545
+ git(["fetch", "-q", "origin", "chant/lifecycle:chant/lifecycle"], b);
546
+ git(["fetch", "-q", "origin", "+refs/heads/chant/lifecycle:refs/remotes/origin/chant/lifecycle"], b);
547
+ return {
548
+ a,
549
+ b,
550
+ remotePath,
551
+ done: async () => {
552
+ await cleanup();
553
+ const { rm } = await import("node:fs/promises");
554
+ await rm(b, { recursive: true, force: true });
555
+ },
556
+ };
557
+ }
558
+ /** A moves the remote on behind B's back, as a wave job pushing beside the record job does. */
559
+ async function advance(a: string, filename: string, content: string): Promise<void> {
560
+ git(["fetch", "-q", "origin", "+refs/heads/chant/lifecycle:refs/remotes/origin/chant/lifecycle"], a);
561
+ await writeBlobToPath("prod", filename, content, `wave: ${filename}`, { cwd: a });
562
+ expect(await pushLifecycle({ cwd: a })).toBe(true);
563
+ }
564
+
565
+ test("a push another writer beat between checkout and push replays on the remote's tip and lands, with both writes kept", async () => {
566
+ const { a, b, remotePath, done } = await twoWriters();
567
+ try {
568
+ await advance(a, "wave.json", '{"wave":1}');
569
+ await writeBlobToPath("prod", "merge.json", '{"merge":1}', "Merge record: abc", { cwd: b });
570
+ // The single push refuses, as pr-record's did before.
571
+ expect((await pushLifecycleReport({ cwd: b })).pushed).toBe(false);
572
+
573
+ expect(await pushLifecycleRebasing({ cwd: b })).toEqual({ pushed: true });
574
+ const tip = git(["rev-parse", "refs/heads/chant/lifecycle"], remotePath).stdout.trim();
575
+ expect(git(["rev-parse", "refs/heads/chant/lifecycle"], b).stdout.trim()).toBe(tip);
576
+ expect(git(["show", `${tip}:prod/merge.json`], remotePath).stdout).toBe('{"merge":1}');
577
+ expect(git(["show", `${tip}:prod/wave.json`], remotePath).stdout).toBe('{"wave":1}');
578
+ expect(git(["show", `${tip}:prod/aws.json`], remotePath).stdout).toBe(JSON.stringify({ a: 1 }));
579
+ // B's commit sits on A's, with its own message and author.
580
+ expect(git(["log", "-1", "--format=%s|%an|%ae", tip], remotePath).stdout.trim()).toBe("Merge record: abc|Record|record@chant.dev");
581
+ expect(git(["log", "-1", "--format=%s", `${tip}^`], remotePath).stdout.trim()).toBe("wave: wave.json");
582
+ // The lease now names the tip that landed, so the next push needs no retry.
583
+ expect(git(["rev-parse", "refs/remotes/origin/chant/lifecycle"], b).stdout.trim()).toBe(tip);
584
+ expect(git(["rev-parse", "--verify", "--quiet", "refs/chant/lifecycle-rebase"], b).exitCode).not.toBe(0);
585
+ } finally {
586
+ await done();
587
+ }
588
+ });
589
+
590
+ test("a commit that changes the file the other writer changed is refused by name, and the local write is kept", async () => {
591
+ const { a, b, done } = await twoWriters();
592
+ try {
593
+ await advance(a, "merge.json", '{"merge":"wave"}');
594
+ await writeBlobToPath("prod", "merge.json", '{"merge":"record"}', "Merge record: abc", { cwd: b });
595
+ const local = git(["rev-parse", "refs/heads/chant/lifecycle"], b).stdout.trim();
596
+ const err = await pushLifecycleRebasing({ cwd: b }).catch((e: unknown) => e);
597
+ expect(err).toBeInstanceOf(LifecyclePushLostError);
598
+ expect((err as LifecyclePushLostError).name).toBe("LifecyclePushLostError");
599
+ expect((err as Error).message).toContain('"Merge record: abc"');
600
+ expect((err as Error).message).toContain("changes files the other writer changed too");
601
+ expect(git(["rev-parse", "refs/heads/chant/lifecycle"], b).stdout.trim()).toBe(local);
602
+ } finally {
603
+ await done();
604
+ }
605
+ });
606
+
607
+ test(`a remote that refuses every push fails after ${LIFECYCLE_PUSH_TRIES} tries with LifecyclePushLostError`, async () => {
608
+ const { b, remotePath, done } = await twoWriters();
609
+ try {
610
+ const hook = join(remotePath, "hooks", "update");
611
+ writeFileSync(hook, "#!/bin/sh\necho 'another writer is mid-push' >&2\nexit 1\n", { mode: 0o755 });
612
+ await writeBlobToPath("prod", "merge.json", '{"merge":1}', "Merge record: abc", { cwd: b });
613
+ const err = await pushLifecycleRebasing({ cwd: b }).catch((e: unknown) => e);
614
+ expect(err).toBeInstanceOf(LifecyclePushLostError);
615
+ expect((err as LifecyclePushLostError).tries).toBe(LIFECYCLE_PUSH_TRIES);
616
+ expect((err as Error).message).toContain(`chant/lifecycle was not pushed to "origin" after ${LIFECYCLE_PUSH_TRIES} tries`);
617
+ } finally {
618
+ await done();
619
+ }
620
+ });
621
+
622
+ test("plywood#22 finding 9: two writers that append lines to one ledger file both land, in push order", async () => {
623
+ const { a, b, remotePath, done } = await twoWriters();
624
+ try {
625
+ // A, a wave job, appends its release record and pushes; B, the record job, appends to the same file from its older copy.
626
+ git(["fetch", "-q", "origin", "+refs/heads/chant/lifecycle:refs/remotes/origin/chant/lifecycle"], a);
627
+ await appendReleaseRecordLine("prod", '{"from":"wave"}', { cwd: a });
628
+ expect(await pushLifecycle({ cwd: a })).toBe(true);
629
+ await appendReleaseRecordLine("prod", '{"from":"record"}', { cwd: b });
630
+ expect(await pushLifecycleRebasing({ cwd: b })).toEqual({ pushed: true });
631
+ const tip = git(["rev-parse", "refs/heads/chant/lifecycle"], remotePath).stdout.trim();
632
+ expect(git(["show", `${tip}:prod/releases.jsonl`], remotePath).stdout).toBe('{"from":"wave"}\n{"from":"record"}\n');
633
+ expect(git(["log", "-1", "--format=%s", tip], remotePath).stdout.trim()).toBe("Release record");
634
+ } finally {
635
+ await done();
636
+ }
637
+ });
638
+
639
+ test("plywood#22 finding 9: a read that finds its unpushed commits diverged from the remote replays them on the remote's tip", async () => {
640
+ const { a, b, remotePath, done } = await twoWriters();
641
+ try {
642
+ await appendReleaseRecordLine("prod", '{"from":"unpushed"}', { cwd: b });
643
+ git(["fetch", "-q", "origin", "+refs/heads/chant/lifecycle:refs/remotes/origin/chant/lifecycle"], a);
644
+ await appendReleaseRecordLine("prod", '{"from":"other"}', { cwd: a });
645
+ expect(await pushLifecycle({ cwd: a })).toBe(true);
646
+ const remoteTip = git(["rev-parse", "refs/heads/chant/lifecycle"], remotePath).stdout.trim();
647
+
648
+ expect(await fetchLifecycleStatus({ cwd: b })).toEqual({ status: "ahead", remote: "origin" });
649
+ await expect(requireLifecycleLedger({ cwd: b })).resolves.toBeUndefined();
650
+ const local = git(["rev-parse", "refs/heads/chant/lifecycle"], b).stdout.trim();
651
+ expect(git(["merge-base", "--is-ancestor", remoteTip, local], b).exitCode).toBe(0);
652
+ expect(git(["show", `${local}:prod/releases.jsonl`], b).stdout).toBe('{"from":"other"}\n{"from":"unpushed"}\n');
653
+ // Nothing was pushed by the read; the next push carries the replayed commit.
654
+ expect(git(["rev-parse", "refs/heads/chant/lifecycle"], remotePath).stdout.trim()).toBe(remoteTip);
655
+ expect(await pushLifecycleRebasing({ cwd: b })).toEqual({ pushed: true });
656
+ } finally {
657
+ await done();
658
+ }
659
+ });
660
+
661
+ test("a read whose unpushed commit rewrote the file the other writer changed still finds the ledger diverged", async () => {
662
+ const { a, b, done } = await twoWriters();
663
+ try {
664
+ await writeBlobToPath("prod", "merge.json", '{"merge":"record"}', "Merge record: abc", { cwd: b });
665
+ await advance(a, "merge.json", '{"merge":"wave"}');
666
+ const got = await fetchLifecycleStatus({ cwd: b });
667
+ expect(got.status).toBe("diverged");
668
+ expect(got.status === "diverged" ? got.stderr : "").toContain("could not be replayed");
669
+ await expect(requireLifecycleLedger({ cwd: b })).rejects.toThrow(/has diverged/);
670
+ } finally {
671
+ await done();
672
+ }
673
+ });
674
+
675
+ test("no remote reads as the local note, as pushLifecycleReport says it", async () => {
676
+ await withTestDir(async (dir) => {
677
+ await initRepo(dir);
678
+ await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: dir });
679
+ expect(await pushLifecycleRebasing({ cwd: dir })).toEqual({ pushed: false, pushWarning: LIFECYCLE_LOCAL_NOTE });
680
+ });
681
+ });
682
+ });
683
+
529
684
  // ── Release ledger plumbing (#568) ──────────────────────────────────────
530
685
 
531
686
  describe("release ledger plumbing", () => {