@intentius/chant 0.124.63 → 0.124.65

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 (185) hide show
  1. package/dist/cli/handlers/approve.d.ts +8 -0
  2. package/dist/cli/handlers/approve.d.ts.map +1 -1
  3. package/dist/cli/handlers/approve.js +27 -4
  4. package/dist/cli/handlers/pr.d.ts.map +1 -1
  5. package/dist/cli/handlers/pr.js +2 -1
  6. package/dist/cli/handlers/release.d.ts +6 -4
  7. package/dist/cli/handlers/release.d.ts.map +1 -1
  8. package/dist/cli/handlers/release.js +101 -16
  9. package/dist/cli/handlers/run.d.ts +30 -1
  10. package/dist/cli/handlers/run.d.ts.map +1 -1
  11. package/dist/cli/handlers/run.js +108 -7
  12. package/dist/cli/main.d.ts.map +1 -1
  13. package/dist/cli/main.js +34 -7
  14. package/dist/cli/parse-args.d.ts.map +1 -1
  15. package/dist/cli/parse-args.js +19 -0
  16. package/dist/cli/registry.d.ts +10 -2
  17. package/dist/cli/registry.d.ts.map +1 -1
  18. package/dist/components/cli-support.d.ts +19 -1
  19. package/dist/components/cli-support.d.ts.map +1 -1
  20. package/dist/components/cli-support.js +11 -3
  21. package/dist/components/component.d.ts +19 -0
  22. package/dist/components/component.d.ts.map +1 -1
  23. package/dist/components/component.schema.json +17 -0
  24. package/dist/components/index.d.ts +1 -1
  25. package/dist/components/index.d.ts.map +1 -1
  26. package/dist/components/release-run.d.ts +48 -0
  27. package/dist/components/release-run.d.ts.map +1 -0
  28. package/dist/components/release-run.js +166 -0
  29. package/dist/components/starter-plugin.d.ts +1 -0
  30. package/dist/components/starter-plugin.d.ts.map +1 -1
  31. package/dist/components/starter-plugin.js +5 -1
  32. package/dist/components/unchanged-inputs.d.ts +81 -0
  33. package/dist/components/unchanged-inputs.d.ts.map +1 -0
  34. package/dist/components/unchanged-inputs.js +122 -0
  35. package/dist/components/verbs/index.d.ts +1 -0
  36. package/dist/components/verbs/index.d.ts.map +1 -1
  37. package/dist/components/verbs/index.js +1 -0
  38. package/dist/components/verbs/release-image.d.ts +36 -0
  39. package/dist/components/verbs/release-image.d.ts.map +1 -0
  40. package/dist/components/verbs/release-image.js +33 -0
  41. package/dist/config.d.ts +18 -0
  42. package/dist/config.d.ts.map +1 -1
  43. package/dist/config.js +1 -0
  44. package/dist/gate-statement.schema.json +4 -2
  45. package/dist/lifecycle/delivery-metrics.d.ts.map +1 -1
  46. package/dist/lifecycle/delivery-metrics.js +4 -2
  47. package/dist/lifecycle/gate-ledger.d.ts +11 -2
  48. package/dist/lifecycle/gate-ledger.d.ts.map +1 -1
  49. package/dist/lifecycle/gate-ledger.js +6 -0
  50. package/dist/lifecycle/gate-seal.d.ts +20 -4
  51. package/dist/lifecycle/gate-seal.d.ts.map +1 -1
  52. package/dist/lifecycle/gate-seal.js +18 -5
  53. package/dist/lifecycle/gate-statement.d.ts +27 -2
  54. package/dist/lifecycle/gate-statement.d.ts.map +1 -1
  55. package/dist/lifecycle/gate-statement.js +37 -2
  56. package/dist/lifecycle/git.d.ts.map +1 -1
  57. package/dist/lifecycle/git.js +6 -1
  58. package/dist/lifecycle/ledger-read.js +1 -1
  59. package/dist/lifecycle/plan-stale.d.ts.map +1 -1
  60. package/dist/lifecycle/plan-stale.js +1 -2
  61. package/dist/lifecycle/publish-declaration.d.ts +20 -0
  62. package/dist/lifecycle/publish-declaration.d.ts.map +1 -1
  63. package/dist/lifecycle/publish-declaration.js +24 -1
  64. package/dist/lifecycle/publish-forge.d.ts.map +1 -1
  65. package/dist/lifecycle/publish-forge.js +1 -2
  66. package/dist/lifecycle/publish-git-ssh.d.ts +82 -0
  67. package/dist/lifecycle/publish-git-ssh.d.ts.map +1 -0
  68. package/dist/lifecycle/publish-git-ssh.js +180 -0
  69. package/dist/lifecycle/publish-homebrew.d.ts +11 -0
  70. package/dist/lifecycle/publish-homebrew.d.ts.map +1 -1
  71. package/dist/lifecycle/publish-homebrew.js +96 -5
  72. package/dist/lifecycle/publish-marketplace.d.ts +36 -2
  73. package/dist/lifecycle/publish-marketplace.d.ts.map +1 -1
  74. package/dist/lifecycle/publish-marketplace.js +173 -30
  75. package/dist/lifecycle/publish-tauri.d.ts.map +1 -1
  76. package/dist/lifecycle/publish-tauri.js +1 -2
  77. package/dist/lifecycle/query.d.ts +2 -2
  78. package/dist/lifecycle/query.d.ts.map +1 -1
  79. package/dist/lifecycle/query.js +3 -3
  80. package/dist/lifecycle/release-cut.d.ts +82 -6
  81. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  82. package/dist/lifecycle/release-cut.js +209 -20
  83. package/dist/lifecycle/release-ledger.d.ts +11 -0
  84. package/dist/lifecycle/release-ledger.d.ts.map +1 -1
  85. package/dist/lifecycle/release-publish.d.ts +13 -0
  86. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  87. package/dist/lifecycle/release-publish.js +5 -0
  88. package/dist/lifecycle/release-revocation.d.ts +4 -3
  89. package/dist/lifecycle/release-revocation.d.ts.map +1 -1
  90. package/dist/lifecycle/release-revocation.js +5 -4
  91. package/dist/lifecycle/release-store.d.ts +49 -3
  92. package/dist/lifecycle/release-store.d.ts.map +1 -1
  93. package/dist/lifecycle/release-store.js +22 -3
  94. package/dist/op/gate.d.ts +1 -1
  95. package/dist/op/gate.d.ts.map +1 -1
  96. package/dist/op/gate.js +2 -1
  97. package/dist/op/op-waves-run.js +5 -3
  98. package/dist/pr-forge.d.ts.map +1 -1
  99. package/dist/pr-forge.js +26 -6
  100. package/dist/release-floors.d.ts +1 -1
  101. package/dist/release-floors.js +1 -1
  102. package/dist/wave-runtime.mjs +284 -283
  103. package/dist/workspace/ci-green.d.ts.map +1 -1
  104. package/dist/workspace/ci-green.js +1 -2
  105. package/dist/workspace/ci-quarantine-report.d.ts.map +1 -1
  106. package/dist/workspace/ci-quarantine-report.js +1 -2
  107. package/dist/workspace/ci-quarantine.d.ts.map +1 -1
  108. package/dist/workspace/ci-quarantine.js +1 -2
  109. package/dist/workspace/delivery-metrics.schema.json +1 -1
  110. package/dist/workspace/intent.d.ts.map +1 -1
  111. package/dist/workspace/intent.js +1 -2
  112. package/dist/workspace/release-candidates.d.ts +9 -1
  113. package/dist/workspace/release-candidates.d.ts.map +1 -1
  114. package/dist/workspace/release-candidates.js +16 -5
  115. package/dist/workspace/release-candidates.schema.json +7 -0
  116. package/dist/workspace/releases.schema.json +54 -2
  117. package/package.json +1 -1
  118. package/src/cli/handlers/approve-external-signature.test.ts +105 -3
  119. package/src/cli/handlers/approve.ts +34 -4
  120. package/src/cli/handlers/pr.ts +2 -1
  121. package/src/cli/handlers/release.ts +91 -16
  122. package/src/cli/handlers/run-unchanged.e2e.test.ts +112 -0
  123. package/src/cli/handlers/run.ts +117 -7
  124. package/src/cli/main.ts +34 -7
  125. package/src/cli/parse-args.ts +15 -0
  126. package/src/cli/registry.ts +10 -2
  127. package/src/components/cli-support.test.ts +53 -0
  128. package/src/components/cli-support.ts +26 -4
  129. package/src/components/component.schema.json +17 -0
  130. package/src/components/component.ts +20 -0
  131. package/src/components/index.ts +1 -0
  132. package/src/components/registry.test.ts +1 -1
  133. package/src/components/release-run.test.ts +127 -0
  134. package/src/components/release-run.ts +188 -0
  135. package/src/components/starter-plugin.ts +5 -0
  136. package/src/components/unchanged-inputs.test.ts +98 -0
  137. package/src/components/unchanged-inputs.ts +151 -0
  138. package/src/components/verbs/index.ts +1 -0
  139. package/src/components/verbs/release-image.ts +52 -0
  140. package/src/config.ts +8 -0
  141. package/src/gate-statement.schema.json +4 -2
  142. package/src/lifecycle/delivery-metrics.ts +4 -2
  143. package/src/lifecycle/gate-ledger.ts +17 -2
  144. package/src/lifecycle/gate-seal.ts +24 -6
  145. package/src/lifecycle/gate-statement.ts +40 -4
  146. package/src/lifecycle/git.test.ts +15 -0
  147. package/src/lifecycle/git.ts +5 -1
  148. package/src/lifecycle/ledger-read.ts +1 -1
  149. package/src/lifecycle/plan-stale.test.ts +3 -4
  150. package/src/lifecycle/plan-stale.ts +1 -2
  151. package/src/lifecycle/publish-declaration.ts +24 -1
  152. package/src/lifecycle/publish-forge.ts +1 -2
  153. package/src/lifecycle/publish-git-ssh.ts +202 -0
  154. package/src/lifecycle/publish-homebrew.test.ts +181 -2
  155. package/src/lifecycle/publish-homebrew.ts +101 -6
  156. package/src/lifecycle/publish-marketplace.test.ts +158 -6
  157. package/src/lifecycle/publish-marketplace.ts +192 -31
  158. package/src/lifecycle/publish-resume.test.ts +40 -0
  159. package/src/lifecycle/publish-tauri.ts +1 -2
  160. package/src/lifecycle/query.ts +3 -3
  161. package/src/lifecycle/release-cut-lane.test.ts +195 -0
  162. package/src/lifecycle/release-cut-override.test.ts +225 -0
  163. package/src/lifecycle/release-cut.test.ts +45 -0
  164. package/src/lifecycle/release-cut.ts +262 -21
  165. package/src/lifecycle/release-ledger.ts +11 -0
  166. package/src/lifecycle/release-publish.ts +18 -0
  167. package/src/lifecycle/release-revocation.ts +5 -4
  168. package/src/lifecycle/release-store.ts +73 -5
  169. package/src/op/gate.ts +2 -1
  170. package/src/op/op-waves-run.ts +4 -2
  171. package/src/pr-forge.ts +25 -6
  172. package/src/pr-requires.test.ts +9 -0
  173. package/src/release-floors.ts +1 -1
  174. package/src/workspace/ci-green.ts +1 -2
  175. package/src/workspace/ci-quarantine-report.test.ts +2 -3
  176. package/src/workspace/ci-quarantine-report.ts +1 -2
  177. package/src/workspace/ci-quarantine.test.ts +2 -3
  178. package/src/workspace/ci-quarantine.ts +1 -2
  179. package/src/workspace/delivery-metrics.schema.json +1 -1
  180. package/src/workspace/delivery-metrics.test.ts +8 -0
  181. package/src/workspace/intent.ts +1 -2
  182. package/src/workspace/release-candidates.schema.json +7 -0
  183. package/src/workspace/release-candidates.ts +19 -5
  184. package/src/workspace/releases.schema.json +54 -2
  185. package/src/workspace/trust/gate-seal.test.ts +44 -0
@@ -17,6 +17,14 @@
17
17
  * component's own file, the member's `chant.config.ts` and the paths its
18
18
  * build steps read.
19
19
  *
20
+ * An image built elsewhere, as by a CI job that builds what the cut's machine
21
+ * can't, is handed to the cut by digest (#4694, `--image
22
+ * <component>=<repository>@sha256:<hex>`). The release records it with its
23
+ * reference in `ref`, and the cut builds nothing for that component: its
24
+ * archive steps, if it has any, don't run, and no earlier release's entry is
25
+ * carried. A deploy under the release runs that image
26
+ * (../components/release-run.ts).
27
+ *
20
28
  * A project with no components (#4046) needs no special case here: its
21
29
  * targets hold the files `chant build --env <env>` writes, each with
22
30
  * `component: null`, and `artifactDigests` is empty.
@@ -31,6 +39,21 @@
31
39
  * all the same, and readers report whether the signature verifies. With
32
40
  * `ci.green.signedSince` declared, a green tag counts only with a valid
33
41
  * statement (`../workspace/ci-green.ts`), so a hand-pushed tag cuts nothing.
42
+ *
43
+ * A lane (#4692): a cut given a lane `ci.green.lanes` declares checks that
44
+ * lane's tags, `ci/green-<lane>/<sha>` and `ci/revoked-<lane>/<sha>`, in place
45
+ * of `ci/green/<sha>` and `ci/revoked/<sha>`, and the cut line names the lane.
46
+ *
47
+ * An override (#4693): a commit with no green tag that counts is cut when the
48
+ * cut asks for it (`overrideGreen`) and a person's override of it stands on
49
+ * the override ledger, `_gates/policy-override.jsonl` (`../override-gate.ts`).
50
+ * The subject is `release-<sha12>`, the plan the commit, and the rule
51
+ * `ci-green` (or `ci-green-<lane>`). It counts when a person the overriders
52
+ * file at base lists wrote it with a reason, sealed under a `release` gate in
53
+ * `identity.gates`. The cut spends it and records it on the cut line. With no
54
+ * override that counts, a cut (not a dry run) records the request for one,
55
+ * which `chant approve policy-override` answers. A revoked commit is never
56
+ * cut, override or not.
34
57
  */
35
58
 
36
59
  import { execFileSync } from "node:child_process";
@@ -53,12 +76,31 @@ import {
53
76
  type Release,
54
77
  type ReleaseArtifact,
55
78
  type ReleaseCut,
79
+ type ReleaseCutOverride,
56
80
  type ReleaseTarget,
57
81
  templateBytesDigest,
58
82
  type TemplateContent,
59
83
  } from "./release-store";
60
84
  import type { CompiledTarget, TargetCompiler } from "../components/release-compile";
61
85
 
86
+ /** The first chant that cuts from a lane's green tag and writes `lane` on the cut line (#4692). */
87
+ export const RELEASE_CUT_LANE_FLOOR = "0.124.64";
88
+ /** The first chant that cuts a commit that is not green under an override and writes `override` on the cut line (#4693). */
89
+ export const RELEASE_CUT_OVERRIDE_FLOOR = "0.124.64";
90
+
91
+ /** The override gate's subject for a cut of `commit` (#4693): `release-<sha12>`. */
92
+ export function greenOverrideSubject(commit: string): string {
93
+ return `release-${commit.slice(0, 12)}`;
94
+ }
95
+
96
+ /** The rule an override of a cut names (#4693): `ci-green`, or `ci-green-<lane>` for a lane's tag. */
97
+ export function greenOverrideRule(lane: string | null): string {
98
+ return lane !== null ? `ci-green-${lane}` : "ci-green";
99
+ }
100
+
101
+ /** How long a recorded request for an override stands before a cut records a fresh one. */
102
+ const OVERRIDE_REQUEST_HOURS = 48;
103
+
62
104
  /** The stable codes a cut refuses with. */
63
105
  export type ReleaseCutCode =
64
106
  | "not-a-git-repository"
@@ -68,6 +110,8 @@ export type ReleaseCutCode =
68
110
  | "release-no-environments"
69
111
  | "release-no-components"
70
112
  | "release-build-inputs-differ"
113
+ | "release-image-invalid"
114
+ | "release-image-unknown-component"
71
115
  | "release-unsigned"
72
116
  | "release-signer-refused"
73
117
  | "declaration-invalid";
@@ -77,6 +121,8 @@ export class ReleaseCutError extends Error {
77
121
  readonly code: ReleaseCutCode,
78
122
  message: string,
79
123
  readonly fix?: string,
124
+ /** The cut recorded a request for an override on `chant/lifecycle` (#4693), which the caller pushes. */
125
+ readonly recorded = false,
80
126
  ) {
81
127
  super(message);
82
128
  this.name = "ReleaseCutError";
@@ -106,6 +152,25 @@ export interface CutRequest {
106
152
  composed?: { branch: string; base: string; sources: string[] };
107
153
  /** The publish channel recorded on the cut (#4168 4.3), in place of `latest`. */
108
154
  channel?: string;
155
+ /**
156
+ * The green lane to check (#4692), one `ci.green.lanes` declares at base:
157
+ * the commit must carry `ci/green-<lane>/<sha>` and no
158
+ * `ci/revoked-<lane>/<sha>`. Recorded on the cut. Absent, the full
159
+ * `ci/green/<sha>` tag is checked.
160
+ */
161
+ lane?: string;
162
+ /**
163
+ * Cut the commit when it has no green tag that counts, under a person's
164
+ * override of it (#4693). Without an override that counts the cut is
165
+ * refused, and a cut that is not a dry run records the request for one.
166
+ */
167
+ overrideGreen?: boolean;
168
+ /**
169
+ * Images built elsewhere and handed to the cut (#4694), by component: each
170
+ * `<repository>@sha256:<hex>`. The release records each as the component's
171
+ * image, and the cut builds nothing for it.
172
+ */
173
+ images?: Readonly<Record<string, string>>;
109
174
  }
110
175
 
111
176
  export interface CutResult {
@@ -118,6 +183,26 @@ export interface CutResult {
118
183
  stored: boolean;
119
184
  /** The components whose artifacts were taken from an earlier release, and that release's digest. */
120
185
  reused: Array<{ component: string; from: string }>;
186
+ /** The images handed to the cut (#4694), by component, as recorded. */
187
+ handed: Array<{ component: string; ref: string; digest: string }>;
188
+ }
189
+
190
+ /** An image reference by digest: `<repository>@sha256:<64 hex>`, the repository without a tag. */
191
+ const IMAGE_BY_DIGEST = /^([a-z0-9]+(?:[._-][a-z0-9]+)*(?::[0-9]+)?(?:\/[a-z0-9]+(?:[._-]+[a-z0-9]+)*)*)@(sha256:[0-9a-f]{64})$/;
192
+
193
+ /**
194
+ * The release artifact for an image handed to the cut (#4694), or why the
195
+ * reference can't be one: it must name its repository and its digest, and no
196
+ * tag, since a tag can move after the cut.
197
+ */
198
+ export function handedImage(component: string, ref: string): ReleaseArtifact | { error: string } {
199
+ const m = IMAGE_BY_DIGEST.exec(ref);
200
+ if (!m) {
201
+ return {
202
+ error: `--image ${component}=${ref}: an image is handed to the cut by digest, as <repository>@sha256:<64 hex digits> with no tag, such as registry.fly.io/app@sha256:${"0".repeat(64)}`,
203
+ };
204
+ }
205
+ return { component, kind: "image", path: "", digest: m[2]!, ref };
121
206
  }
122
207
 
123
208
  function git(top: string, args: string[]): string {
@@ -137,17 +222,18 @@ function tryGit(top: string, args: string[]): string | null {
137
222
  * and the tags on it that were ignored for want of a valid statement
138
223
  * (#4031). The tags are judged by `green`, the declaration's `ci.green` at
139
224
  * base, with the runner keys read at its branch's tip; with no `ci.green`,
140
- * every tag counts.
225
+ * every tag counts. With `lane` (#4692), that lane's tags are read.
141
226
  */
142
227
  export async function greenState(
143
228
  top: string,
144
229
  sha: string,
145
230
  green: import("../workspace/declaration").CiGreen | null = null,
231
+ lane?: string,
146
232
  ): Promise<{ state: "green" | "revoked" | "none"; ignored: Array<{ tag: string; status: string; reason: string }> }> {
147
233
  const { judgedCiTags } = await import("./release-revocation");
148
234
  let tags: Awaited<ReturnType<typeof judgedCiTags>>;
149
235
  try {
150
- tags = await judgedCiTags(top, green);
236
+ tags = await judgedCiTags(top, green, lane);
151
237
  } catch (err) {
152
238
  const { WorkspaceReadError } = await import("../workspace/declaration");
153
239
  if (err instanceof WorkspaceReadError) throw new ReleaseCutError("declaration-invalid", err.message);
@@ -198,10 +284,109 @@ interface Prepared {
198
284
  releaseRule: ReturnType<typeof import("../workspace/identity").releaseRuleFrom>;
199
285
  /** The components to build, by the environment they are built in. */
200
286
  toBuild: Map<string, string[]>;
201
- /** The artifacts carried from an earlier release. */
287
+ /** The artifacts carried from an earlier release, and the images handed to the cut. */
202
288
  carried: ReleaseArtifact[];
203
289
  reused: CutResult["reused"];
290
+ handed: CutResult["handed"];
204
291
  member: string | null;
292
+ /** The lane the commit was checked in, or null for the full green tag. */
293
+ lane: string | null;
294
+ /** The override the commit is cut under when it is not green (#4693), or null. */
295
+ override: ReleaseCutOverride | null;
296
+ }
297
+
298
+ /**
299
+ * Decide the override of a cut of `commit`, which has no green tag that
300
+ * counts (#4693), as `decideOverride` decides any: against the overriders
301
+ * file and, when `sealed`, the signers at base. With none that counts and
302
+ * `record`, the request for one is appended unless one stands.
303
+ */
304
+ async function greenOverride(req: {
305
+ top: string;
306
+ cwd: string;
307
+ commit: string;
308
+ lane: string | null;
309
+ sealed: boolean;
310
+ record: boolean;
311
+ now: string;
312
+ }): Promise<{ override: Omit<ReleaseCutOverride, "green" | "tag"> } | { override: null; why: string; fix: string; recorded: boolean }> {
313
+ const og = await import("../override-gate");
314
+ const { readOverrideLedger, recordOverrideDenial } = await import("./override-ledger");
315
+ const { resolveBase } = await import("../workspace/trust/provenance");
316
+ const subject = greenOverrideSubject(req.commit);
317
+ const rules = [greenOverrideRule(req.lane)];
318
+ const base = resolveBase(req.top).commit;
319
+ const overriders = base ? og.overridersAt(req.top, base) : null;
320
+ const signers = req.sealed && base ? (await import("../gate-decision")).gateSignersAt(req.top, base) : undefined;
321
+ const ledger = await readOverrideLedger({ cwd: req.cwd });
322
+ const verdict = og.decideOverride({
323
+ ledger,
324
+ applied: ledger.applied,
325
+ subject,
326
+ planDigest: req.commit,
327
+ rules,
328
+ overriders: overriders?.principals ?? [],
329
+ mode: req.sealed ? "sealed" : "ledger",
330
+ ...(signers ? { signers } : {}),
331
+ now: req.now,
332
+ });
333
+ if (verdict.status === "overridden") {
334
+ const o = verdict.override;
335
+ return { override: { by: o.by, at: o.at, reason: o.reason, digest: o.digest, sealed: o.sealed } };
336
+ }
337
+ let recorded = false;
338
+ if (req.record && !verdict.standing) {
339
+ await recordOverrideDenial(
340
+ {
341
+ subject,
342
+ planDigest: req.commit,
343
+ rules,
344
+ timestamp: req.now,
345
+ expiresAt: new Date(Date.parse(req.now) + OVERRIDE_REQUEST_HOURS * 3_600_000).toISOString(),
346
+ description: `release cut of commit ${req.commit.slice(0, 12)}, which has no ${req.lane !== null ? `ci/green-${req.lane}` : "ci/green"} tag that counts`,
347
+ },
348
+ { cwd: req.cwd },
349
+ );
350
+ recorded = true;
351
+ }
352
+ const notes = [
353
+ ...verdict.refusals.map((r) => `an override does not count: ${r}`),
354
+ ...(verdict.status === "moved" ? [`${verdict.by} overrode another commit or rule (${verdict.was ?? "no digest"}), which counts for nothing here`] : []),
355
+ recorded
356
+ ? `the request for an override of ${subject} is recorded on chant/lifecycle`
357
+ : verdict.standing
358
+ ? `the request for an override of ${subject} has stood since ${verdict.standing.timestamp}`
359
+ : `a cut with --yes records the request for an override of ${subject}`,
360
+ ];
361
+ const who = !overriders?.active
362
+ ? `${og.OVERRIDERS_PATH} at base does not exist, so nobody may override it yet. Once it lists a person, they may`
363
+ : overriders.principals.length > 0
364
+ ? `${overriders.principals.join(", ")} may`
365
+ : `${og.OVERRIDERS_PATH} at base lists nobody, so nobody may`;
366
+ return {
367
+ override: null,
368
+ why: notes.join("; "),
369
+ fix: `${who} override it with: ${og.overrideCommand(subject, rules, req.sealed)}, and then cut again with --override-green.`,
370
+ recorded,
371
+ };
372
+ }
373
+
374
+ /**
375
+ * The lane `name` as the declaration at base declares it (#4692), or a
376
+ * `declaration-invalid` refusal when there is no `ci.green` or it declares
377
+ * no such lane.
378
+ */
379
+ async function declaredLane(green: import("../workspace/declaration").CiGreen | null, name: string): Promise<string> {
380
+ if (!green) {
381
+ throw new ReleaseCutError("declaration-invalid", `the cut asks for lane ${JSON.stringify(name)}, and chant.workspace.json at base declares no ci.green, so it has no lanes`);
382
+ }
383
+ const { laneOf, WorkspaceReadError } = await import("../workspace/declaration");
384
+ try {
385
+ return laneOf(green, name).name;
386
+ } catch (err) {
387
+ if (err instanceof WorkspaceReadError) throw new ReleaseCutError("declaration-invalid", err.message);
388
+ throw err;
389
+ }
205
390
  }
206
391
 
207
392
  /**
@@ -210,7 +395,7 @@ interface Prepared {
210
395
  * asks, the tree is clean, every environment compiles with the same build
211
396
  * steps, and which artifacts are carried from an earlier release.
212
397
  */
213
- async function prepare(req: CutRequest): Promise<Prepared> {
398
+ async function prepare(req: CutRequest, record = false): Promise<Prepared> {
214
399
  const cwd = resolve(req.cwd);
215
400
  const top = tryGit(cwd, ["rev-parse", "--show-toplevel"]);
216
401
  if (!top) throw new ReleaseCutError("not-a-git-repository", "a release is cut from a commit, and this directory is not in a git repository");
@@ -220,21 +405,34 @@ async function prepare(req: CutRequest): Promise<Prepared> {
220
405
  const { scopeSource } = await import("../workspace/write-scope");
221
406
  const { releaseRuleFrom } = await import("../workspace/identity");
222
407
  const source = scopeSource(cwd);
223
- const { state, ignored } = await greenState(top, commit, source.declaration?.ci?.green ?? null);
408
+ const green = source.declaration?.ci?.green ?? null;
409
+ const lane = req.lane !== undefined ? await declaredLane(green, req.lane) : null;
410
+ const { state, ignored } = await greenState(top, commit, green, lane ?? undefined);
411
+ // Who may cut is the declaration's identity.gates.release, read at base.
412
+ const releaseRule = releaseRuleFrom(source);
413
+ let override: ReleaseCutOverride | null = null;
224
414
  if (state !== "green") {
225
415
  const why = ignored.length > 0 ? `; ignored: ${ignored.map((t) => `${t.tag} (${t.status}): ${t.reason}`).join("; ")}` : "";
226
- throw new ReleaseCutError(
227
- state === "revoked" ? "release-commit-revoked" : "release-commit-not-green",
416
+ // #4692: a lane's tags are ci/green-<lane>/ and ci/revoked-<lane>/.
417
+ const greenTag = lane !== null ? `ci/green-${lane}` : "ci/green";
418
+ const revokedTag = lane !== null ? `ci/revoked-${lane}` : "ci/revoked";
419
+ const message =
228
420
  state === "revoked"
229
- ? `commit ${commit.slice(0, 12)} has a ci/revoked tag: it went red after it was green, so no release is cut from it`
230
- : ignored.some((t) => t.tag.startsWith("ci/green/"))
231
- ? `commit ${commit.slice(0, 12)} has no ci/green tag that counts, so no release is cut from it${why}`
232
- : `commit ${commit.slice(0, 12)} has no ci/green tag, so no release is cut from it`,
233
- "Check out a green commit (`chant ci last-green` names the newest) after fetching the tags: git fetch origin --tags",
234
- );
421
+ ? `commit ${commit.slice(0, 12)} has a ${revokedTag} tag: it went red after it was green, so no release is cut from it`
422
+ : ignored.some((t) => t.tag.startsWith(`${greenTag}/`))
423
+ ? `commit ${commit.slice(0, 12)} has no ${greenTag} tag that counts, so no release is cut from it${why}`
424
+ : `commit ${commit.slice(0, 12)} has no ${greenTag} tag, so no release is cut from it`;
425
+ const fix = `Check out a green commit (\`chant ci last-green${lane !== null ? ` --lane ${lane}` : ""}\` names the newest) after fetching the tags: git fetch origin --tags`;
426
+ if (state === "revoked") {
427
+ throw new ReleaseCutError("release-commit-revoked", req.overrideGreen ? `${message}, and an override does not cut a revoked commit` : message, fix);
428
+ }
429
+ if (!req.overrideGreen) throw new ReleaseCutError("release-commit-not-green", message, fix);
430
+ // #4693: a person's override of this commit lets it through.
431
+ const now = (req.now ?? (() => new Date()))().toISOString();
432
+ const decided = await greenOverride({ top, cwd, commit, lane, sealed: releaseRule.requirement !== null, record, now });
433
+ if (decided.override === null) throw new ReleaseCutError("release-commit-not-green", `${message}; ${decided.why}`, decided.fix, decided.recorded);
434
+ override = { green: false, tag: `${greenTag}/${commit}`, ...decided.override };
235
435
  }
236
- // Who may cut is the declaration's identity.gates.release, read at base.
237
- const releaseRule = releaseRuleFrom(source);
238
436
  if (releaseRule.requirement && req.sign === undefined) {
239
437
  throw new ReleaseCutError(
240
438
  "release-unsigned",
@@ -285,15 +483,34 @@ async function prepare(req: CutRequest): Promise<Prepared> {
285
483
  );
286
484
  }
287
485
 
486
+ // #4694: an image handed to the cut is the component's, in place of a build.
487
+ const enabled = new Set(compiled.flatMap((t) => t.components));
488
+ const handedArtifacts: ReleaseArtifact[] = [];
489
+ for (const [component, ref] of Object.entries(req.images ?? {})) {
490
+ if (!enabled.has(component)) {
491
+ throw new ReleaseCutError(
492
+ "release-image-unknown-component",
493
+ `--image names "${component}", which is not a component enabled in any environment of this member`,
494
+ enabled.size > 0 ? `The components are: ${[...enabled].sort().join(", ")}` : undefined,
495
+ );
496
+ }
497
+ const artifact = handedImage(component, ref);
498
+ if ("error" in artifact) throw new ReleaseCutError("release-image-invalid", artifact.error);
499
+ handedArtifacts.push(artifact);
500
+ }
501
+ const handedTo = new Set(handedArtifacts.map((a) => a.component));
502
+
288
503
  // Which environment each component's artifacts are built in: the first one it is enabled in.
289
504
  const firstEnv = new Map<string, CompiledTarget>();
290
- for (const t of compiled) for (const c of t.components) if (!firstEnv.has(c) && (t.buildSteps[c]?.length ?? 0) > 0) firstEnv.set(c, t);
505
+ for (const t of compiled) {
506
+ for (const c of t.components) if (!firstEnv.has(c) && !handedTo.has(c) && (t.buildSteps[c]?.length ?? 0) > 0) firstEnv.set(c, t);
507
+ }
291
508
 
292
509
  // git names paths from its top with symlinks resolved (/private/var on macOS).
293
510
  const realCwd = realpathSync(cwd);
294
511
  const previous = firstEnv.size > 0 ? await previousRelease(top, commit, cwd) : undefined;
295
512
  const reused: CutResult["reused"] = [];
296
- const artifacts: ReleaseArtifact[] = [];
513
+ const artifacts: ReleaseArtifact[] = [...handedArtifacts];
297
514
  const toBuild = new Map<string, string[]>();
298
515
  for (const [component, target] of firstEnv) {
299
516
  const prior = previous?.artifactDigests.filter((a) => a.component === component) ?? [];
@@ -322,7 +539,10 @@ async function prepare(req: CutRequest): Promise<Prepared> {
322
539
  toBuild,
323
540
  carried: artifacts,
324
541
  reused,
542
+ handed: handedArtifacts.map((a) => ({ component: a.component, ref: a.ref!, digest: a.digest })),
325
543
  member: ledger.members.length > 0 ? ledger.members.join("/") : null,
544
+ lane,
545
+ override,
326
546
  };
327
547
  }
328
548
 
@@ -367,10 +587,16 @@ export interface CutPlan {
367
587
  build: Array<{ component: string; env: string }>;
368
588
  /** The components whose artifacts would be carried from an earlier release. */
369
589
  reused: CutResult["reused"];
590
+ /** The images handed to the cut (#4694), by component. */
591
+ handed: CutResult["handed"];
370
592
  /** Each component's publish steps, with the environments whose deploy runs them. */
371
593
  publishSteps: Array<{ component: string; kind: string; to: string | null; envs: string[] }>;
372
594
  /** Whether the release gate in identity.gates requires a signed cut. */
373
595
  signatureRequired: boolean;
596
+ /** The green lane the commit was checked in (#4692), or null for the full green tag. */
597
+ lane: string | null;
598
+ /** The override the cut would run under and spend (#4693), when the commit is not green; null when it is. */
599
+ override: ReleaseCutOverride | null;
374
600
  }
375
601
 
376
602
  /**
@@ -437,8 +663,11 @@ export async function planRelease(req: CutRequest): Promise<CutPlan> {
437
663
  targets: targets.map((t) => ({ env: t.env, params: t.params, templates: t.templates.map(({ component, path }) => ({ component, path })), ...(t.trees ? { trees: t.trees } : {}) })),
438
664
  build,
439
665
  reused: p.reused,
666
+ handed: p.handed,
440
667
  publishSteps: [...steps.values()],
441
668
  signatureRequired: p.releaseRule.requirement !== null,
669
+ lane: p.lane,
670
+ override: p.override,
442
671
  };
443
672
  }
444
673
 
@@ -448,15 +677,17 @@ export async function planRelease(req: CutRequest): Promise<CutPlan> {
448
677
  * push. Throws {@link ReleaseCutError} before anything is written when the
449
678
  * commit isn't green, the tree is dirty, or an environment can't be compiled
450
679
  * to the same artifacts, and `ReleaseLabelError` (./release-store.ts) when the
451
- * label is taken or the release already carries another one.
680
+ * label is taken or the release already carries another one. The one write
681
+ * before a refusal is the request for an override (#4693), when the cut asks
682
+ * for one and none stands; the error's `recorded` says so.
452
683
  *
453
684
  * The cut line names its run (#4027): the CI run's id and origin in CI, and
454
685
  * outside CI an id minted from the cut's time, `local-<epoch ms>`, with the
455
686
  * origin `{ forge: "local" }`.
456
687
  */
457
688
  export async function cutRelease(req: CutRequest): Promise<CutResult> {
458
- const p = await prepare(req);
459
- const { cwd, commit, compiled, releaseRule, reused } = p;
689
+ const p = await prepare(req, true);
690
+ const { cwd, commit, compiled, releaseRule, reused, handed } = p;
460
691
  const artifacts = [...p.carried];
461
692
  for (const env of p.envs) {
462
693
  const names = p.toBuild.get(env);
@@ -496,17 +727,26 @@ export async function cutRelease(req: CutRequest): Promise<CutResult> {
496
727
  }
497
728
  const stored = await persistRelease(release, templates, { cwd });
498
729
  const ci = resolveCiRun(req.env ?? process.env);
730
+ const runId = ci?.runId ?? `local-${Date.parse(timestamp)}`;
731
+ // #4693: the override is spent before the cut line names it, so it lets one cut through.
732
+ if (p.override) {
733
+ const { appliedOverride } = await import("../override-gate");
734
+ const { recordOverridesApplied } = await import("./override-ledger");
735
+ await recordOverridesApplied([appliedOverride({ subject: greenOverrideSubject(commit), digest: p.override.digest, at: p.override.at, by: p.override.by }, { timestamp, runId, commit })], { cwd });
736
+ }
499
737
  const outcome = await appendCut(
500
738
  {
501
739
  releaseDigest: release.releaseDigest,
502
740
  label: req.label,
503
741
  actor: req.actor,
504
742
  timestamp,
505
- runId: ci?.runId ?? `local-${Date.parse(timestamp)}`,
743
+ runId,
506
744
  runOrigin: ci?.runOrigin ?? { forge: "local" },
507
745
  signature,
508
746
  ...(req.composed ? { composed: req.composed } : {}),
509
747
  ...(req.channel ? { channel: req.channel } : {}),
748
+ ...(p.lane !== null ? { lane: p.lane } : {}),
749
+ ...(p.override ? { override: p.override } : {}),
510
750
  },
511
751
  { cwd },
512
752
  );
@@ -516,5 +756,6 @@ export async function cutRelease(req: CutRequest): Promise<CutResult> {
516
756
  label: outcome.appended ? outcome.cut.label : outcome.label,
517
757
  stored: stored.written,
518
758
  reused,
759
+ handed,
519
760
  };
520
761
  }
@@ -242,6 +242,17 @@ export interface ReleaseRecord {
242
242
  * partway. Absent on every other record.
243
243
  */
244
244
  redeploys?: ReleaseRef;
245
+ /**
246
+ * Optional: set when a release skipped this component (#4695) because the
247
+ * inputs it declares were the same as in the release the environment ran
248
+ * it from. Names that environment's record, whose `digest`, `gitSha`,
249
+ * `manifestDigest`, `digestKind` and `inputDigest` this record repeats:
250
+ * nothing was deployed, and the environment still runs that deploy, now
251
+ * under this record's `releaseDigest`. Written from chant
252
+ * `UNCHANGED_INPUTS_FLOOR` (../components/unchanged-inputs.ts); absent on
253
+ * every deploy.
254
+ */
255
+ unchangedSince?: ReleaseRef;
245
256
  /**
246
257
  * Optional: the release this deploy came from (#4026, ws-104), the
247
258
  * `releaseDigest` of `_releases/<releaseDigest>.json`. Written by
@@ -84,6 +84,8 @@ export interface PublishItem {
84
84
  digest?: string;
85
85
  /** True when the destination already held it, so nothing was uploaded. */
86
86
  present?: boolean;
87
+ /** True when the destination refused it and the target turns a refusal into a warning (a marketplace's `onRefusal: "warn"`, #4698), so it was not published. */
88
+ refused?: boolean;
87
89
  /** Set on a file attached to what the target publishes (#4049): an SBOM or the release's provenance statement. */
88
90
  attachment?: "sbom" | "provenance";
89
91
  /** The SBOM file an npm package carries at its root (#4049). */
@@ -121,6 +123,13 @@ export interface PublishedTarget {
121
123
  destination: string;
122
124
  /** Each thing published, in order. */
123
125
  items: PublishItem[];
126
+ /**
127
+ * Set when the destination refused the reveal and the target declares that
128
+ * a warning (#4698): why, with the items `refused`. The publish goes on, and
129
+ * the target is not recorded as revealed, so the same publish run again
130
+ * reveals it again.
131
+ */
132
+ warning?: string;
124
133
  }
125
134
 
126
135
  /** Injected into the targets, so tests drive them with fakes. */
@@ -131,6 +140,10 @@ export interface PublishDeps {
131
140
  npm?: string;
132
141
  /** The vsce executable the VS Code Marketplace target runs (#4676). Default: `vsce` on `PATH`. */
133
142
  vsce?: string;
143
+ /** The git executable the homebrew target runs to push over SSH (#4699). Default: `git` on `PATH`. */
144
+ git?: string;
145
+ /** The ssh executable git runs for it (#4699). Default: `ssh` on `PATH`. */
146
+ ssh?: string;
134
147
  /** How a target waits between polls of a registry (#4244). Default: a timer. */
135
148
  sleep?: (ms: number) => Promise<void>;
136
149
  /** The clock a target's wait reads (#4244). Default: `Date.now`. */
@@ -613,6 +626,11 @@ export async function runPublish(req: {
613
626
  return fail(err, target, "reveal", stagedNames, revealedNames);
614
627
  }
615
628
  published.push(p);
629
+ if (p.warning) {
630
+ // Refused, and the target makes that a warning (#4698): not recorded, so a run of the same publish tries it again.
631
+ say(` warning: ${target.name}: ${p.warning}`);
632
+ continue;
633
+ }
616
634
  revealedNames.push(target.name);
617
635
  await write(target, "revealed", p.items, {});
618
636
  }
@@ -49,17 +49,18 @@ function tryGit(top: string, args: string[]): string | null {
49
49
  /**
50
50
  * The ci tags at `top`, judged against `green` at base: the green branch's
51
51
  * tip on `origin`, else the local branch, else `HEAD`. With no `ci.green`
52
- * every tag counts. Throws `WorkspaceReadError` (`declaration-invalid`) when
53
- * `ci.green.signedSince` names no commit here.
52
+ * every tag counts. With `lane` (#4692), that lane's tags, `ci/green-<lane>/`
53
+ * and `ci/revoked-<lane>/`. Throws `WorkspaceReadError` (`declaration-invalid`)
54
+ * when `ci.green.signedSince` names no commit here.
54
55
  */
55
- export async function judgedCiTags(top: string, green: CiGreen | null): Promise<CiTags> {
56
+ export async function judgedCiTags(top: string, green: CiGreen | null, lane?: string): Promise<CiTags> {
56
57
  const { readCiTags } = await import("../workspace/ci-green");
57
58
  const base = green
58
59
  ? (tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${green.branch}^{commit}`]) ??
59
60
  tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${green.branch}^{commit}`]) ??
60
61
  tryGit(top, ["rev-parse", "HEAD"]))
61
62
  : null;
62
- return readCiTags(top, green, base);
63
+ return readCiTags(top, green, base, lane);
63
64
  }
64
65
 
65
66
  /**