@intentius/chant 0.124.63 → 0.124.64

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 (123) 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 +83 -16
  9. package/dist/cli/main.d.ts.map +1 -1
  10. package/dist/cli/main.js +18 -6
  11. package/dist/cli/parse-args.d.ts.map +1 -1
  12. package/dist/cli/parse-args.js +12 -0
  13. package/dist/cli/registry.d.ts +5 -1
  14. package/dist/cli/registry.d.ts.map +1 -1
  15. package/dist/config.d.ts +18 -0
  16. package/dist/config.d.ts.map +1 -1
  17. package/dist/config.js +1 -0
  18. package/dist/gate-statement.schema.json +4 -2
  19. package/dist/lifecycle/gate-ledger.d.ts +11 -2
  20. package/dist/lifecycle/gate-ledger.d.ts.map +1 -1
  21. package/dist/lifecycle/gate-ledger.js +6 -0
  22. package/dist/lifecycle/gate-seal.d.ts +20 -4
  23. package/dist/lifecycle/gate-seal.d.ts.map +1 -1
  24. package/dist/lifecycle/gate-seal.js +18 -5
  25. package/dist/lifecycle/gate-statement.d.ts +27 -2
  26. package/dist/lifecycle/gate-statement.d.ts.map +1 -1
  27. package/dist/lifecycle/gate-statement.js +37 -1
  28. package/dist/lifecycle/plan-stale.d.ts.map +1 -1
  29. package/dist/lifecycle/plan-stale.js +1 -2
  30. package/dist/lifecycle/publish-declaration.d.ts +20 -0
  31. package/dist/lifecycle/publish-declaration.d.ts.map +1 -1
  32. package/dist/lifecycle/publish-declaration.js +24 -1
  33. package/dist/lifecycle/publish-forge.d.ts.map +1 -1
  34. package/dist/lifecycle/publish-forge.js +1 -2
  35. package/dist/lifecycle/publish-git-ssh.d.ts +82 -0
  36. package/dist/lifecycle/publish-git-ssh.d.ts.map +1 -0
  37. package/dist/lifecycle/publish-git-ssh.js +180 -0
  38. package/dist/lifecycle/publish-homebrew.d.ts +11 -0
  39. package/dist/lifecycle/publish-homebrew.d.ts.map +1 -1
  40. package/dist/lifecycle/publish-homebrew.js +96 -4
  41. package/dist/lifecycle/publish-marketplace.d.ts +36 -2
  42. package/dist/lifecycle/publish-marketplace.d.ts.map +1 -1
  43. package/dist/lifecycle/publish-marketplace.js +173 -29
  44. package/dist/lifecycle/publish-tauri.d.ts.map +1 -1
  45. package/dist/lifecycle/publish-tauri.js +1 -2
  46. package/dist/lifecycle/release-cut.d.ts +51 -5
  47. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  48. package/dist/lifecycle/release-cut.js +165 -16
  49. package/dist/lifecycle/release-publish.d.ts +13 -0
  50. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  51. package/dist/lifecycle/release-publish.js +5 -0
  52. package/dist/lifecycle/release-revocation.d.ts +4 -3
  53. package/dist/lifecycle/release-revocation.d.ts.map +1 -1
  54. package/dist/lifecycle/release-revocation.js +5 -4
  55. package/dist/lifecycle/release-store.d.ts +32 -0
  56. package/dist/lifecycle/release-store.d.ts.map +1 -1
  57. package/dist/lifecycle/release-store.js +11 -0
  58. package/dist/op/activities/activity-contracts.d.ts +4 -4
  59. package/dist/op/gate.d.ts +1 -1
  60. package/dist/op/gate.d.ts.map +1 -1
  61. package/dist/op/gate.js +2 -1
  62. package/dist/pr-forge.d.ts.map +1 -1
  63. package/dist/pr-forge.js +26 -6
  64. package/dist/release-floors.d.ts +1 -1
  65. package/dist/release-floors.js +1 -1
  66. package/dist/wave-runtime.mjs +284 -283
  67. package/dist/workspace/ci-green.d.ts.map +1 -1
  68. package/dist/workspace/ci-green.js +1 -2
  69. package/dist/workspace/ci-quarantine-report.d.ts.map +1 -1
  70. package/dist/workspace/ci-quarantine-report.js +1 -2
  71. package/dist/workspace/ci-quarantine.d.ts.map +1 -1
  72. package/dist/workspace/ci-quarantine.js +1 -2
  73. package/dist/workspace/intent.d.ts.map +1 -1
  74. package/dist/workspace/intent.js +1 -2
  75. package/dist/workspace/release-candidates.d.ts +9 -1
  76. package/dist/workspace/release-candidates.d.ts.map +1 -1
  77. package/dist/workspace/release-candidates.js +16 -4
  78. package/dist/workspace/release-candidates.schema.json +7 -0
  79. package/dist/workspace/releases.schema.json +47 -0
  80. package/package.json +1 -1
  81. package/src/cli/handlers/approve-external-signature.test.ts +105 -3
  82. package/src/cli/handlers/approve.ts +34 -4
  83. package/src/cli/handlers/pr.ts +2 -1
  84. package/src/cli/handlers/release.ts +75 -16
  85. package/src/cli/main.ts +18 -6
  86. package/src/cli/parse-args.ts +9 -0
  87. package/src/cli/registry.ts +5 -1
  88. package/src/config.ts +8 -0
  89. package/src/gate-statement.schema.json +4 -2
  90. package/src/lifecycle/gate-ledger.ts +17 -2
  91. package/src/lifecycle/gate-seal.ts +24 -6
  92. package/src/lifecycle/gate-statement.ts +40 -3
  93. package/src/lifecycle/plan-stale.test.ts +3 -4
  94. package/src/lifecycle/plan-stale.ts +1 -2
  95. package/src/lifecycle/publish-declaration.ts +24 -1
  96. package/src/lifecycle/publish-forge.ts +1 -2
  97. package/src/lifecycle/publish-git-ssh.ts +202 -0
  98. package/src/lifecycle/publish-homebrew.test.ts +181 -2
  99. package/src/lifecycle/publish-homebrew.ts +101 -5
  100. package/src/lifecycle/publish-marketplace.test.ts +158 -6
  101. package/src/lifecycle/publish-marketplace.ts +192 -30
  102. package/src/lifecycle/publish-resume.test.ts +40 -0
  103. package/src/lifecycle/publish-tauri.ts +1 -2
  104. package/src/lifecycle/release-cut-lane.test.ts +177 -0
  105. package/src/lifecycle/release-cut-override.test.ts +213 -0
  106. package/src/lifecycle/release-cut.ts +198 -17
  107. package/src/lifecycle/release-publish.ts +18 -0
  108. package/src/lifecycle/release-revocation.ts +5 -4
  109. package/src/lifecycle/release-store.ts +44 -0
  110. package/src/op/gate.ts +2 -1
  111. package/src/pr-forge.ts +25 -6
  112. package/src/pr-requires.test.ts +9 -0
  113. package/src/release-floors.ts +1 -1
  114. package/src/workspace/ci-green.ts +1 -2
  115. package/src/workspace/ci-quarantine-report.test.ts +2 -3
  116. package/src/workspace/ci-quarantine-report.ts +1 -2
  117. package/src/workspace/ci-quarantine.test.ts +2 -3
  118. package/src/workspace/ci-quarantine.ts +1 -2
  119. package/src/workspace/intent.ts +1 -2
  120. package/src/workspace/release-candidates.schema.json +7 -0
  121. package/src/workspace/release-candidates.ts +19 -4
  122. package/src/workspace/releases.schema.json +47 -0
  123. package/src/workspace/trust/gate-seal.test.ts +44 -0
@@ -28,7 +28,7 @@ import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git
28
28
  import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
29
29
  import { ledgerRecordingOff, NO_RECORD_ENV } from "../../lifecycle/no-record";
30
30
  import { checkGateSignature, gateSealPayload, gateSealVersion, WEBAUTHN_SEAL_KIND, type SealedGateApproval } from "../../lifecycle/gate-seal";
31
- import { gateStatement, readExternalSignature, type GateStatement } from "../../lifecycle/gate-statement";
31
+ import { gateBindingProblem, gateStatement, readExternalSignature, type GateStatement } from "../../lifecycle/gate-statement";
32
32
  import type { GateApprovalSeal } from "../../lifecycle/gate-ledger";
33
33
  import type { TrustPolicy } from "../../workspace/trust/policy";
34
34
  import { readFileSync } from "node:fs";
@@ -176,6 +176,7 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
176
176
  ...(ctx.args.env !== undefined ? { environment: ctx.args.env } : {}),
177
177
  ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
178
178
  ...(ctx.args.at !== undefined ? { at: ctx.args.at } : {}),
179
+ ...(ctx.args.binding !== undefined ? { binding: ctx.args.binding } : {}),
179
180
  allowSameOrigin: ctx.args.allowSameOrigin,
180
181
  };
181
182
  const statement = await gateApprovalStatement(opName, gate, shared);
@@ -187,6 +188,7 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
187
188
  (statement.relayedBy !== null ? ` --relayed-by ${statement.relayedBy}` : "") +
188
189
  (statement.planDigest !== null ? ` --plan ${statement.planDigest}` : "") +
189
190
  (statement.environment !== null ? ` --env ${statement.environment}` : "") +
191
+ (statement.binding !== null ? ` --binding ${shellQuote(statement.binding)}` : "") +
190
192
  ` --at ${statement.timestamp} --signature <file>`,
191
193
  ));
192
194
  return 0;
@@ -218,6 +220,7 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
218
220
  ...(ctx.args.sign !== undefined ? { sign: ctx.args.sign } : {}),
219
221
  ...(ctx.args.signature !== undefined ? { signature: ctx.args.signature } : {}),
220
222
  ...(ctx.args.at !== undefined ? { at: ctx.args.at } : {}),
223
+ ...(ctx.args.binding !== undefined ? { binding: ctx.args.binding } : {}),
221
224
  ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
222
225
  });
223
226
  if (!outcome.ok) return 1;
@@ -313,6 +316,14 @@ export interface GateApprovalOptions {
313
316
  signature?: string;
314
317
  /** `--at <timestamp>` (#4646): the statement's time, which `--statement` fixes and `--signature` records. */
315
318
  at?: string;
319
+ /**
320
+ * `--binding <text>` (#4697): a line the relay sets for the approver's
321
+ * signature to cover as well, such as a platform's deploy id and an
322
+ * expiry. Signed last (seal version 3) and recorded as `binding`. It goes
323
+ * with `--statement`, `--signature` or `--sign`, and must be the same on
324
+ * `--statement` and `--signature`.
325
+ */
326
+ binding?: string;
316
327
  /** Where the workspace and the key file are looked up from. Defaults to the process's directory. */
317
328
  cwd?: string;
318
329
  /** Replaces the lexicon evaluator a gate policy is loaded from. For tests. */
@@ -643,6 +654,13 @@ async function approveGate(
643
654
  `Pass the timestamp \`chant approve ${opName} ${gate} --statement\` printed.`,
644
655
  );
645
656
  }
657
+ if (opts.binding !== undefined) {
658
+ if (!statementOnly && opts.signature === undefined && opts.sign === undefined) {
659
+ return refuse("--binding is a line the approver's signature covers, so it goes with --statement, --signature or --sign");
660
+ }
661
+ const problem = gateBindingProblem(opts.binding);
662
+ if (problem !== null) return refuse(`--binding takes one line of printable text, and ${problem}`);
663
+ }
646
664
  let timestamp = new Date().toISOString();
647
665
  if (opts.at !== undefined) {
648
666
  const at = Date.parse(opts.at);
@@ -667,6 +685,7 @@ async function approveGate(
667
685
  ...(relayedBy ? { relayedBy } : {}),
668
686
  timestamp,
669
687
  ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
688
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
670
689
  };
671
690
  if (statementOnly) {
672
691
  const { CHANT_VERSION } = await import("../../chant-version");
@@ -697,8 +716,9 @@ async function approveGate(
697
716
  try {
698
717
  const key = resolveSigningKey(opts.sign, cwd);
699
718
  try {
700
- // #3947: a seal over a checkpoint digest is seal version 2.
701
- seal = { ...sealGateApproval(key.file, sealed), ...(gateSealVersion(sealed) === 2 ? { version: 2 as const } : {}) };
719
+ // #3947, #4697: a seal over a checkpoint digest is seal version 2, and one over a binding 3.
720
+ const version = gateSealVersion(sealed);
721
+ seal = { ...sealGateApproval(key.file, sealed), ...(version !== 1 ? { version } : {}) };
702
722
  } finally {
703
723
  key.cleanup();
704
724
  }
@@ -718,6 +738,7 @@ async function approveGate(
718
738
  ...(relayedBy ? { relayedBy } : {}),
719
739
  timestamp,
720
740
  ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
741
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
721
742
  seal,
722
743
  });
723
744
  if (why !== null) {
@@ -748,6 +769,7 @@ async function approveGate(
748
769
  ...(relayedBy ? { relayedBy } : {}),
749
770
  timestamp,
750
771
  ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
772
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
751
773
  ...(seal ? { seal } : {}),
752
774
  }).roles;
753
775
  let policyDecision: GatePolicyDecision | undefined;
@@ -797,6 +819,7 @@ async function approveGate(
797
819
  ...(url ? { url } : {}),
798
820
  ...(planDigest !== undefined ? { planDigest } : {}),
799
821
  ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
822
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
800
823
  ...(environment !== undefined ? { environment } : {}),
801
824
  ...(releaseDigest !== undefined ? { releaseDigest } : {}),
802
825
  ...(changeSet !== undefined ? { changeSet } : {}),
@@ -819,6 +842,7 @@ async function approveGate(
819
842
  (record.seal ? `, signed with ${record.seal.kind === WEBAUTHN_SEAL_KIND ? "passkey " : ""}${record.seal.key}` : "") +
820
843
  push.suffix,
821
844
  ));
845
+ if (record.binding !== undefined) console.error(formatInfo(`The signature also binds ${JSON.stringify(record.binding)} (--binding).`));
822
846
  if (record.planDigest) {
823
847
  console.error(formatInfo(
824
848
  `This approves the plan ${record.planDigest}` +
@@ -891,7 +915,13 @@ function externalSeal(
891
915
  : `the ${sig.kind === "ssh" ? "ssh signature" : "passkey's assertion"} does not verify for ${sealed.resolvedBy} over this approval's statement: ${r.reason}`,
892
916
  };
893
917
  }
894
- return { seal: { ...candidate, key: r.key, ...(gateSealVersion(sealed) === 2 ? { version: 2 as const } : {}) } };
918
+ const version = gateSealVersion(sealed);
919
+ return { seal: { ...candidate, key: r.key, ...(version !== 1 ? { version } : {}) } };
920
+ }
921
+
922
+ /** `text` quoted for a POSIX shell, for a command line a hint prints. */
923
+ function shellQuote(text: string): string {
924
+ return /^[\w@%+=:,./-]+$/.test(text) ? text : `'${text.replace(/'/g, `'\\''`)}'`;
895
925
  }
896
926
 
897
927
  /**
@@ -1496,8 +1496,9 @@ async function beforeMergeChecks(ctx: CommandContext): Promise<PrBeforeMerge | n
1496
1496
  );
1497
1497
  }
1498
1498
  // The apply's own statuses never hold it back: chant ci run's, and the report's.
1499
+ // Nor does the plan's: a policy denial fails it, and the denial is only recorded when the apply judges it (plywood#66).
1499
1500
  // #4550: under a product's words its own prefix too.
1500
- const ignore = [...new Set([productContext(activeProductWords(), gate), productContext(activeProductWords(), PR_APPLY_GATE), `chant/${gate}`, `chant/${PR_APPLY_GATE}`, prStatusContext("apply", member)])];
1501
+ const ignore = [...new Set([productContext(activeProductWords(), gate), productContext(activeProductWords(), PR_APPLY_GATE), `chant/${gate}`, `chant/${PR_APPLY_GATE}`, prStatusContext("apply", member), prStatusContext("plan"), `${prStatusContext("plan")}/`])];
1501
1502
  // ws-106 gives the declaration no way to leave a check out, so with no --requires all four are asked (#4336, #4607).
1502
1503
  const requires = await checkPrRequires(forge, args.pr, head, { ignore, ...(only ? { only: only.checks } : {}) });
1503
1504
  for (const r of requires) console.error(formatInfo(`${r.name}: ${r.passed ? "passed" : r.pending ? "pending" : "unmet"}, ${r.reason}`));
@@ -1,11 +1,13 @@
1
1
  /**
2
2
  * `chant release` (#4026, ws-104): the release is what graduates.
3
3
  *
4
- * release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json]
4
+ * release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--lane <name>] [--json]
5
5
  * a dry run of a cut of this member from the checkout's HEAD, which must be
6
- * clean, on trunk and pushed, and green (#4027); `--yes` cuts, records,
6
+ * clean, on trunk and pushed, and green (#4027), or green in a lane with
7
+ * `--lane` or `release.lane` (#4692); `--yes` cuts, records,
7
8
  * and tags the commit `release/<label>` locally;
8
- * --sign signs the cut with the actor's ssh key (#4031); `--src`, `-o` and
9
+ * --sign signs the cut with the actor's ssh key (#4031); `--override-green`
10
+ * cuts a commit that is not green under a person's override (#4693); `--src`, `-o` and
9
11
  * `--lexicon` shape the build of a project with no components (#4046)
10
12
  * release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json]
11
13
  * publish a cut release (#4027) to the targets release.publish declares
@@ -17,7 +19,7 @@
17
19
  * release verify <label|digest> [--json]
18
20
  * check the release's signature offline against .chant/allowed_signers
19
21
  * at the release's commit (#4049)
20
- * release candidates [--env <env>] [--forge-issues] [--json]
22
+ * release candidates [--env <env>] [--lane <name>] [--forge-issues] [--json]
21
23
  * the green commits of trunk a release can be cut from, each with what it
22
24
  * would ship, and what each environment runs (#4168 4.2)
23
25
  * release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json]
@@ -47,7 +49,7 @@ import { parseParamFlags } from "../build-params-cli";
47
49
  import type { CommandContext } from "../registry";
48
50
 
49
51
  const USAGE =
50
- "chant release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--channel <tag>] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release candidates [--env <env>] [--forge-issues] [--json] | release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
52
+ "chant release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--channel <tag>] [--lane <name>] [--override-green] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release candidates [--env <env>] [--lane <name>] [--forge-issues] [--json] | release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
51
53
 
52
54
  /** The build inputs `release cut` and `release compile` share. */
53
55
  function compileInputs(
@@ -94,6 +96,23 @@ export function sameWithYes(argv: readonly string[]): string {
94
96
  return ["chant", ...argv.filter((a) => a !== "--json" && a !== "--yes"), "--yes"].map(quote).join(" ");
95
97
  }
96
98
 
99
+ /**
100
+ * The green lane a cut or a candidates read checks (#4692): `--lane`, else
101
+ * `release.lane` in the member's chant.config.ts at `cwd`, else none. A
102
+ * config that can't be loaded is warned about and read as naming none, so the
103
+ * full green tag is checked.
104
+ */
105
+ async function laneOf(ctx: CommandContext, cwd: string): Promise<string | undefined> {
106
+ if (ctx.args.lane !== undefined) return ctx.args.lane;
107
+ try {
108
+ const { loadChantConfig } = await import("../../config");
109
+ return (await loadChantConfig(cwd)).config.release?.lane;
110
+ } catch (err) {
111
+ if (!ctx.args.json) console.error(formatWarning({ message: `release.lane was not read, so the full green tag is checked: ${err instanceof Error ? err.message : String(err)}` }));
112
+ return undefined;
113
+ }
114
+ }
115
+
97
116
  function describeActorSource(source: import("../../lifecycle/release-workstation").ActorSource): string {
98
117
  switch (source) {
99
118
  case "flag":
@@ -130,6 +149,14 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
130
149
  return 1;
131
150
  }
132
151
  const label = positional ?? args.label ?? null;
152
+ // #4693: the reason is the override's, written by the person who overrides.
153
+ if (args.reason !== undefined) {
154
+ console.error(formatError({
155
+ message: "release cut takes no --reason: an override's reason is on the override itself",
156
+ hint: "Cut with --override-green: it names the chant approve policy-override command that records the override and its reason.",
157
+ }));
158
+ return 1;
159
+ }
133
160
  const dryRun = args.yes !== true;
134
161
  const cwd = resolve(".");
135
162
  const { spawnTargetCompiler, ReleaseCompileError } = await import("../../components/release-compile");
@@ -226,6 +253,8 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
226
253
  if (args.at !== undefined && top && commit) checkout = at.checkoutCommit(top, cwd, commit);
227
254
  const cutCwd = checkout?.memberDir ?? cwd;
228
255
  const compiler = spawnTargetCompiler(compileInputs(ctx, params, cutCwd, label));
256
+ // #4692: the lane is the commit's own config's under --at.
257
+ const lane = await laneOf(ctx, cutCwd);
229
258
  const request = {
230
259
  cwd: cutCwd,
231
260
  compiler,
@@ -234,6 +263,8 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
234
263
  ...(args.sign !== undefined ? { sign: args.sign } : {}),
235
264
  ...(composed ? { composed } : {}),
236
265
  ...(args.channel ? { channel: args.channel } : {}),
266
+ ...(lane !== undefined ? { lane } : {}),
267
+ ...(args.overrideGreen ? { overrideGreen: true } : {}),
237
268
  };
238
269
 
239
270
  if (dryRun) {
@@ -274,13 +305,19 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
274
305
  return 0;
275
306
  }
276
307
  const name = plan.label ? formatBold(plan.label) : "an unlabelled release";
308
+ const greenIn = plan.override
309
+ ? `not green: no ${plan.override.tag.slice(0, plan.override.tag.lastIndexOf("/"))} tag`
310
+ : plan.lane !== null
311
+ ? `green in lane ${plan.lane}`
312
+ : "green";
277
313
  const where = composed
278
- ? ` (on ${trunk!.remote}/${composed.branch}, composed on ${composed.base.slice(0, 12)} from ${composed.sources.length} trunk commit(s), green)`
314
+ ? ` (on ${trunk!.remote}/${composed.branch}, composed on ${composed.base.slice(0, 12)} from ${composed.sources.length} trunk commit(s), ${greenIn})`
279
315
  : trunk
280
- ? ` (on ${trunk.remote}/${trunk.branch}, green)`
316
+ ? ` (on ${trunk.remote}/${trunk.branch}, ${greenIn})`
281
317
  : "";
282
318
  console.log(`Dry run: cut ${name} from commit ${plan.commit.slice(0, 12)}${where}`);
283
319
  if (args.channel) console.log(` channel ${args.channel}: a publish moves ${args.channel}, not latest`);
320
+ if (plan.override) console.log(` under the override by ${plan.override.by} at ${plan.override.at}${plan.override.sealed ? ", sealed" : ""}: ${plan.override.reason}; the cut spends it`);
284
321
  if (plan.alreadyCut) console.log(` already cut as ${plan.alreadyCut}: the cut would record nothing new`);
285
322
  console.log(` actor ${actor} (from ${describeActorSource(who.source)})`);
286
323
  console.log(` run ${ci ? `${ci.runId} (${ci.runOrigin.forge})` : "minted on this machine at the cut (local)"}`);
@@ -337,7 +374,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
337
374
  if (args.json) {
338
375
  console.log(
339
376
  JSON.stringify(
340
- { dryRun: false, release: result.release, label: result.label, cut: result.cut, stored: result.stored, reused: result.reused, actor, actorSource: who.source, tag: tagged, composed: composed ?? null, channel: args.channel ?? null, next },
377
+ { dryRun: false, release: result.release, label: result.label, cut: result.cut, stored: result.stored, reused: result.reused, actor, actorSource: who.source, tag: tagged, composed: composed ?? null, channel: args.channel ?? null, lane: lane ?? null, next },
341
378
  null,
342
379
  2,
343
380
  ),
@@ -346,8 +383,9 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
346
383
  const name = result.label ? formatBold(result.label) : "unlabelled release";
347
384
  if (result.cut) console.error(formatSuccess(`Cut ${name}: ${result.release.releaseDigest}`));
348
385
  else console.error(formatSuccess(`Already cut${result.label ? ` as ${formatBold(result.label)}` : ""}: ${result.release.releaseDigest}`));
349
- console.error(` commit ${result.release.commit}${composed ? `, composed on ${composed.base.slice(0, 12)} on ${composed.branch}` : ""}`);
386
+ console.error(` commit ${result.release.commit}${composed ? `, composed on ${composed.base.slice(0, 12)} on ${composed.branch}` : ""}${lane !== undefined ? `, green in lane ${lane}` : ""}`);
350
387
  if (args.channel) console.error(` channel ${args.channel}`);
388
+ if (result.cut?.override) console.error(` not green: cut under the override by ${result.cut.override.by}: ${result.cut.override.reason}`);
351
389
  if (result.cut) console.error(` ${result.cut.signature ? `signed by ${result.cut.actor}` : `not signed; actor ${result.cut.actor}`}, run ${result.cut.runId}`);
352
390
  console.error(` artifacts ${result.release.artifactDigests.length}, targets ${result.release.targets.map((t) => `${t.env} (${t.templates.length} template${t.templates.length === 1 ? "" : "s"})`).join(", ")}`);
353
391
  for (const r of result.reused) console.error(` ${r.component}: artifacts unchanged, carried from ${r.from}`);
@@ -361,6 +399,12 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
361
399
  return 0;
362
400
  } catch (err) {
363
401
  if (err instanceof ws.WorkstationCheckError || err instanceof ReleaseCutError || err instanceof at.CutAtError) {
402
+ // #4693: a request for an override goes where the person who answers it reads.
403
+ if (err instanceof ReleaseCutError && err.recorded) {
404
+ const { pushLifecycleReport } = await import("../../lifecycle/git");
405
+ const push = await pushLifecycleReport({ cwd }).catch(() => ({ pushed: false, pushWarning: undefined }));
406
+ if (push.pushWarning) console.error(formatWarning({ message: push.pushWarning }));
407
+ }
364
408
  return fail(err.code, err.message, err.fix);
365
409
  }
366
410
  if (err instanceof ReleaseLabelError) return fail(err.code, err.message);
@@ -495,8 +539,9 @@ export async function runReleasePublish(ctx: CommandContext): Promise<number> {
495
539
  const hint = promoteHint();
496
540
  if (hint) say(hint);
497
541
  } else {
498
- for (const p of published) for (const i of p.items) say(` ${i.present ? "already there" : "published"}: ${describeItem(i)}`);
499
- console.error(formatSuccess(`Published ${name} to ${published.length} target(s)`));
542
+ for (const p of published) for (const i of p.items) say(` ${i.refused ? "refused" : i.present ? "already there" : "published"}: ${describeItem(i)}`);
543
+ const refused = published.filter((p) => p.warning);
544
+ console.error(formatSuccess(`Published ${name} to ${published.length - refused.length} target(s)${refused.length > 0 ? `; ${refused.length} refused it, with a warning` : ""}`));
500
545
  }
501
546
  return 0;
502
547
  }
@@ -559,7 +604,14 @@ export async function runReleaseVerify(ctx: CommandContext): Promise<number> {
559
604
  */
560
605
  export async function runReleaseCandidates(ctx: CommandContext): Promise<number> {
561
606
  const { releaseCandidatesDocument } = await import("../../workspace/release-candidates");
562
- const doc = await releaseCandidatesDocument({ cwd: resolve("."), ...(ctx.args.env ? { env: ctx.args.env } : {}), ...(ctx.args.branch ? { branch: ctx.args.branch } : {}), ...(ctx.args.forgeIssues ? { forgeIssues: {} } : {}) });
607
+ const lane = await laneOf(ctx, resolve("."));
608
+ const doc = await releaseCandidatesDocument({
609
+ cwd: resolve("."),
610
+ ...(ctx.args.env ? { env: ctx.args.env } : {}),
611
+ ...(ctx.args.branch ? { branch: ctx.args.branch } : {}),
612
+ ...(lane !== undefined ? { lane } : {}),
613
+ ...(ctx.args.forgeIssues ? { forgeIssues: {} } : {}),
614
+ });
563
615
  if (ctx.args.json) {
564
616
  console.log(JSON.stringify(doc, null, 2));
565
617
  return "error" in doc ? 1 : 0;
@@ -576,8 +628,10 @@ export async function runReleaseCandidates(ctx: CommandContext): Promise<number>
576
628
  console.error(`No candidates: this clone knows no ${doc.branch}. Fetch it: git fetch origin ${doc.branch} --tags`);
577
629
  return 0;
578
630
  }
579
- if (doc.pending.length > 0) console.log(`${doc.pending.length} commit(s) on ${doc.branch} after the newest candidate are not green yet`);
580
- if (doc.candidates.length === 0) console.log(`No green commit on ${doc.branch}${doc.since ? ` since ${doc.since.slice(0, 12)}` : ""} to cut from.`);
631
+ const greenIn = doc.lane !== null ? `green in lane ${doc.lane}` : "green";
632
+ if (doc.lane !== null) console.log(`Lane ${doc.lane}: candidates carry ci/green-${doc.lane}/<sha>`);
633
+ if (doc.pending.length > 0) console.log(`${doc.pending.length} commit(s) on ${doc.branch} after the newest candidate are not ${greenIn} yet`);
634
+ if (doc.candidates.length === 0) console.log(`No ${greenIn} commit on ${doc.branch}${doc.since ? ` since ${doc.since.slice(0, 12)}` : ""} to cut from.`);
581
635
  for (const c of doc.candidates) {
582
636
  const tags = [...(c.newFor.length > 0 ? [`new for ${c.newFor.join(", ")}`] : []), ...(c.cut.length > 0 ? [`cut as ${c.cut.join(", ")}`] : [])];
583
637
  console.log(`${c.commit.slice(0, 12)} ${c.subject}${tags.length > 0 ? ` (${tags.join("; ")})` : ""}`);
@@ -596,7 +650,7 @@ export async function runReleaseCandidates(ctx: CommandContext): Promise<number>
596
650
  // --forge-issues: why a pull request's issues were not read, once per reason.
597
651
  const unread = new Set([...doc.candidates.flatMap((c) => c.changes), ...doc.pending].map((ch) => ch.closes?.reason).filter((r): r is string => typeof r === "string"));
598
652
  for (const r of unread) console.error(`Issues not read from the forge: ${r}`);
599
- if (doc.candidates.length > 0) console.error(`Cut one: chant release cut <label> --at <sha>`);
653
+ if (doc.candidates.length > 0) console.error(`Cut one: chant release cut <label> --at <sha>${doc.lane !== null && ctx.args.lane !== undefined ? ` --lane ${doc.lane}` : ""}`);
600
654
  return 0;
601
655
  }
602
656
 
@@ -622,8 +676,13 @@ export async function runReleaseList(ctx: CommandContext): Promise<number> {
622
676
  const newest = r.cuts.at(-1);
623
677
  const signature = newest ? (newest.signatureCheck.status === "verified" ? `signed by ${newest.actor}` : newest.signatureCheck.status) : "-";
624
678
  // #4033: a release cut from a revoked commit says so at the end of its line, and why on stderr.
625
- console.log(`${(r.label ?? "-").padEnd(16)} ${r.releaseDigest} ${r.commit.slice(0, 12)} ${signature} ${where}${r.revoked ? " revoked" : ""}`);
679
+ // #4692: a release cut from a lane's green tag names the lane.
680
+ const lane = r.cuts.find((c) => c.lane !== undefined)?.lane;
681
+ const overridden = r.cuts.some((c) => c.override !== undefined);
682
+ console.log(`${(r.label ?? "-").padEnd(16)} ${r.releaseDigest} ${r.commit.slice(0, 12)} ${signature} ${where}${lane !== undefined ? ` lane ${lane}` : ""}${overridden ? " not green" : ""}${r.revoked ? " revoked" : ""}`);
626
683
  if (newest?.signatureCheck.status === "unverified") console.error(` ${r.label ?? r.releaseDigest}: ${newest.signatureCheck.reason}`);
684
+ // #4693: a release cut under an override says the commit was not green.
685
+ for (const c of r.cuts) if (c.override) console.error(` ${r.label ?? r.releaseDigest}: not green (no ${c.override.tag}), cut under the override by ${c.override.by}: ${c.override.reason}`);
627
686
  if (r.revoked) {
628
687
  const { describeRevocation } = await import("../../lifecycle/release-revocation");
629
688
  console.error(` ${r.label ?? r.releaseDigest}: revoked by ${r.revoked.tag}, ${describeRevocation(r.revoked)}`);
package/src/cli/main.ts CHANGED
@@ -451,7 +451,8 @@ CI:
451
451
  Releases:
452
452
  release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>]
453
453
  [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>]
454
- [--actor <name>] [--sign [<key file>]] [--channel <tag>] [--json]
454
+ [--actor <name>] [--sign [<key file>]] [--channel <tag>]
455
+ [--lane <name>] [--override-green] [--json]
455
456
  A dry run of a cut of this member from HEAD, which
456
457
  must be clean, on trunk and pushed, and carry a
457
458
  ci/green tag: compile every environment in the
@@ -475,7 +476,13 @@ Releases:
475
476
  A green commit of a pushed chant/compose/<name>
476
477
  branch is cut too, recording its base and sources.
477
478
  --channel <tag> records the tag a publish moves in
478
- place of latest.
479
+ place of latest. --lane <name> (or release.lane in
480
+ chant.config.ts) checks a ci.green lane's tag,
481
+ ci/green-<lane>/<sha>, in place of ci/green.
482
+ --override-green cuts a commit that is not green
483
+ under a person's override, recorded with chant
484
+ approve policy-override release-<sha12>; the cut
485
+ spends it and records who and why.
479
486
  release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)...
480
487
  [--yes] [--json]
481
488
  Cherry-pick the chosen trunk changes, in trunk order,
@@ -484,12 +491,14 @@ Releases:
484
491
  that exists; stops on a conflict, naming the change
485
492
  and files, and writes nothing. A dry run unless --yes,
486
493
  which moves the branch and pushes it.
487
- release candidates [--env <env>] [--forge-issues] [--json]
494
+ release candidates [--env <env>] [--lane <name>] [--forge-issues] [--json]
488
495
  The green commits of trunk a release can be cut from,
489
496
  newest first, each with the commits, work items, pull
490
497
  requests and flags it would ship, and what each
491
- environment runs. --forge-issues asks the forge which
492
- issues each pull request closes, once per pull request
498
+ environment runs. --lane reads a lane's green tags,
499
+ as release cut --lane checks them. --forge-issues asks
500
+ the forge which issues each pull request closes, once
501
+ per pull request
493
502
  release publish <label|digest> [--yes] [--allow-unsigned]
494
503
  [--require-provenance] [--json]
495
504
  Publish a cut release to the targets release.publish
@@ -668,7 +677,10 @@ Ops:
668
677
  <file|-> --at <time> then records a signature made
669
678
  elsewhere over them (an ssh signature, or a passkey's
670
679
  WebAuthn assertion checked against .chant/trust.json's
671
- passkeys), which counts as --sign does (#4646)
680
+ passkeys), which counts as --sign does (#4646).
681
+ --binding <text> adds a line the relay sets (a deploy
682
+ id and an expiry, say) that the signature covers too;
683
+ pass the same on --statement and --signature (#4697)
672
684
  --resume then starts the CI job that waits at the
673
685
  gate again (GitHub re-run, GitLab retry, Forgejo
674
686
  dispatch) with CHANT_FORGE_TOKEN
@@ -93,6 +93,7 @@ const BOOLEAN_FLAGS = new Set([
93
93
  "--allow-code",
94
94
  "--allow-skip",
95
95
  "--allow-unsigned",
96
+ "--override-green",
96
97
  "--require-provenance",
97
98
  "--root-only",
98
99
  "--generated",
@@ -564,6 +565,9 @@ export function parseArgs(args: string[]): ParsedArgs {
564
565
  // `chant ci run|serve --status-url <template>` (#4097): the link a job's status carries, in place of an https --report-url.
565
566
  result.statusUrl = args[++i];
566
567
  if (!result.statusUrl || result.statusUrl.startsWith("-")) throw new Error("--status-url needs a URL template: --status-url https://host/reports/{key}");
568
+ } else if (arg === "--override-green") {
569
+ // `chant release cut --override-green` (#4693): cut a commit that is not green under a person's override.
570
+ result.overrideGreen = true;
567
571
  } else if (arg === "--allow-unsigned") {
568
572
  // `chant release publish --allow-unsigned` (#4049).
569
573
  result.allowUnsigned = true;
@@ -975,6 +979,10 @@ export function parseArgs(args: string[]): ParsedArgs {
975
979
  if (!result.signature || (result.signature.startsWith("-") && result.signature !== "-")) {
976
980
  throw new Error("--signature needs a file holding the signature, or - for stdin: --signature <file|->");
977
981
  }
982
+ } else if (arg === "--binding") {
983
+ // `chant approve <op> <gate> --statement|--signature|--sign --binding <text>` (#4697): a line the relay sets for the signature to cover.
984
+ result.binding = args[++i];
985
+ if (!result.binding || result.binding.startsWith("-")) throw new Error("--binding needs the line the signature binds, which does not start with -: --binding <text>");
978
986
  } else if (arg === "--relayed-by") {
979
987
  // `chant approve <op> <gate> --relayed-by <principal>` and `workspace points answer <id> --relayed-by <principal>` (#3402):
980
988
  // who carried the approval or answer to chant for the person it names.
@@ -1213,6 +1221,7 @@ export function parseArgs(args: string[]): ParsedArgs {
1213
1221
  result.ciWait = true;
1214
1222
  } else if (arg === "--lane") {
1215
1223
  // `chant ci last-green --lane <name>` and `chant ci base --lane <name>` (#4662): a green lane's tags and phases.
1224
+ // `chant release cut|candidates --lane <name>` (#4692): a cut from that lane's green tag.
1216
1225
  result.lane = args[++i];
1217
1226
  } else if (arg === "--runner") {
1218
1227
  // `chant ci quarantine filter --runner nextest|playwright|list` (#4677): the runner the filter is for.
@@ -377,6 +377,8 @@ export interface ParsedArgs {
377
377
  prs?: number[];
378
378
  /** `chant release cut --channel <tag>` (#4168 4.3): the tag a publish of the release moves in place of `latest`. */
379
379
  channel?: string;
380
+ /** `chant release cut --override-green` (#4693): cut a commit that is not green under a person's override on the override ledger. */
381
+ overrideGreen?: boolean;
380
382
  /**
381
383
  * `chant components pr-plan|pr-apply --forge github|gitlab|forgejo` (#3183)
382
384
  * — post the note and the commit status on this forge, with the client
@@ -707,6 +709,8 @@ export interface ParsedArgs {
707
709
  statement?: boolean;
708
710
  /** `chant approve <op> <gate> --signature <file|->` (#4646): a signature made elsewhere over the statement. */
709
711
  signature?: string;
712
+ /** `chant approve <op> <gate> --binding <text>` (#4697): a line the relay sets, signed last with the statement. */
713
+ binding?: string;
710
714
  /**
711
715
  * `chant approve <op> <gate> --relayed-by <principal>` and `chant workspace
712
716
  * points answer <id> --relayed-by <principal>` (#3402): the principal that
@@ -925,7 +929,7 @@ export interface ParsedArgs {
925
929
  since?: string;
926
930
  /** `chant ci verdict --wait` (#4644) — read again until no required phase is pending. */
927
931
  ciWait?: boolean;
928
- /** `chant ci last-green --lane <name>` and `chant ci base --lane <name>` (#4662) — a ci.green lane. */
932
+ /** `chant ci last-green --lane <name>` and `chant ci base --lane <name>` (#4662) — a ci.green lane. `chant release cut --lane <name>` and `chant release candidates --lane <name>` (#4692) — check that lane's green tags. */
929
933
  lane?: string;
930
934
  /** `chant ci base --phase <name>` (#4643) — the ci.green phase whose base to find. `chant ci quarantine filter --phase <name>` (#4677) — the phase whose runner takes the filter. */
931
935
  phase?: string;
package/src/config.ts CHANGED
@@ -109,6 +109,7 @@ export const ChantConfigSchema = z.object({
109
109
  release: z.object({
110
110
  autoRecord: z.boolean().optional(),
111
111
  publish: z.array(PublishDeclarationSchema).optional(),
112
+ lane: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "a ci.green lane name: lowercase letters, digits and dashes").optional(),
112
113
  }).optional(),
113
114
  // Strict: a misspelt key here would leave Ops on the local runtime with
114
115
  // nothing said (#2523).
@@ -371,6 +372,13 @@ export interface ChantConfig {
371
372
  * the order given. See ./lifecycle/publish-declaration.ts.
372
373
  */
373
374
  publish?: PublishDeclaration[];
375
+ /**
376
+ * The green lane `chant release cut` and `chant release candidates` check
377
+ * when `--lane` is not given (#4692): one `ci.green.lanes` declares in
378
+ * chant.workspace.json. The commit must then carry `ci/green-<lane>/<sha>`
379
+ * rather than `ci/green/<sha>`.
380
+ */
381
+ lane?: string;
374
382
  };
375
383
 
376
384
  /** Defaults for `chant run` and its subcommands (#2523). */
@@ -2,7 +2,7 @@
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
3
  "$id": "https://intentius.io/chant/schemas/gate-statement/v1/gate-statement.schema.json",
4
4
  "title": "chant-gate-statement/v1",
5
- "description": "What `chant approve <op> <gate> --statement` prints (#4646): the exact bytes an approval of the gate signs, for a signature made outside chant. Sign `statement` (the bytes of `text`) with an ssh key in the `chant-gate` namespace, or with a passkey whose WebAuthn challenge is `challenge`, then record it with `chant approve <op> <gate> --actor <resolvedBy> --at <timestamp> --signature <file>`, passing the same `--relayed-by`, `--plan` and `--env`. Written by chant 0.124.63 and newer. Readers ignore fields they do not know; a field is only ever added within a version.",
5
+ "description": "What `chant approve <op> <gate> --statement` prints (#4646): the exact bytes an approval of the gate signs, for a signature made outside chant. Sign `statement` (the bytes of `text`) with an ssh key in the `chant-gate` namespace, or with a passkey whose WebAuthn challenge is `challenge`, then record it with `chant approve <op> <gate> --actor <resolvedBy> --at <timestamp> --signature <file>`, passing the same `--relayed-by`, `--plan`, `--env` and `--binding`. Written by chant 0.124.63 and newer. Readers ignore fields they do not know; a field is only ever added within a version.",
6
6
  "type": "object",
7
7
  "required": [
8
8
  "schema",
@@ -15,6 +15,7 @@
15
15
  "relayedBy",
16
16
  "timestamp",
17
17
  "checkpointDigest",
18
+ "binding",
18
19
  "sealVersion",
19
20
  "namespace",
20
21
  "text",
@@ -33,7 +34,8 @@
33
34
  "relayedBy": { "type": ["string", "null"], "description": "Who relays the approval (--relayed-by). When not null the statement has a `relayed-by <principal>` line after the time." },
34
35
  "timestamp": { "type": "string", "description": "The approval's time, ISO 8601 UTC with milliseconds. The sixth line. Pass it as --at when recording the signature." },
35
36
  "checkpointDigest": { "type": ["string", "null"], "description": "The checkpoint a resumed run carries its outputs from. When not null the statement ends with a `checkpoint <digest>` line." },
36
- "sealVersion": { "enum": [1, 2], "description": "2 when the statement signs a checkpoint digest, else 1." },
37
+ "binding": { "type": ["string", "null"], "maxLength": 512, "description": "A line the relay set with --binding (#4697) for the signature to cover as well, such as its deploy id and an expiry: one line of printable text, at most 512 UTF-8 bytes, which chant records with the approval and does not interpret. When not null the statement ends with a `binding <text>` line, after any checkpoint line." },
38
+ "sealVersion": { "enum": [1, 2, 3], "description": "3 when the statement signs a binding, else 2 when it signs a checkpoint digest, else 1." },
37
39
  "namespace": { "const": "chant-gate", "description": "The ssh signature namespace (`ssh-keygen -Y sign -n chant-gate`)." },
38
40
  "text": { "type": "string", "description": "The statement as UTF-8 text: the lines joined by LF, no final newline." },
39
41
  "statement": { "type": "string", "contentEncoding": "base64", "description": "The same bytes, base64. These are what is signed." },
@@ -161,6 +161,14 @@ export interface GateResolutionRecord {
161
161
  * resumes (`resume: true`) whose run stored a checkpoint. A seal covers it.
162
162
  */
163
163
  checkpointDigest?: string;
164
+ /**
165
+ * The line the relay set for the approver's signature to bind as well
166
+ * (#4697, `chant approve --binding`), such as a platform's deploy id and
167
+ * an expiry. Printable text on one line; chant reads nothing in it. Set
168
+ * only on an approval signed with --sign or --signature, whose seal (version
169
+ * 3) signs it.
170
+ */
171
+ binding?: string;
164
172
  /**
165
173
  * The environment this approval is for (#2574), copied off the pending fact
166
174
  * it answers. Set for a component gate, whose ledger is keyed by component
@@ -313,9 +321,10 @@ export interface GateApprovalSeal {
313
321
  /**
314
322
  * The seal's version (#3947). `2` on a seal over an approval that carries a
315
323
  * `checkpointDigest`, whose payload signs the digest as one more line.
316
- * Absent on every other seal, which is version 1.
324
+ * `3` on a seal over an approval with a `binding` (#4697), which signs one
325
+ * more line after that. Absent on every other seal, which is version 1.
317
326
  */
318
- version?: 2;
327
+ version?: 2 | 3;
319
328
  }
320
329
 
321
330
  export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">;
@@ -638,6 +647,12 @@ export function parseGateLedger(
638
647
  malformed++;
639
648
  continue;
640
649
  }
650
+ // #4697: and for the binding a seal signs. A line break would make the statement's lines ambiguous.
651
+ const rawBinding: unknown = (parsed as { binding?: unknown }).binding;
652
+ if (rawBinding !== undefined && (typeof rawBinding !== "string" || /[\r\n\u2028\u2029]/.test(rawBinding))) {
653
+ malformed++;
654
+ continue;
655
+ }
641
656
  // #4020: a commit or run id of the wrong type is dropped, so a reader can trust the type without losing the line.
642
657
  // #4551: and so is a `changeSet` that is not a digest.
643
658
  for (const key of ["gitSha", "runId", "changeSet"] as const) {
@@ -42,6 +42,12 @@ export interface SealedGateApproval {
42
42
  timestamp: string;
43
43
  /** The checkpoint the approval lets a run resume from (#3947), when it carries one. */
44
44
  checkpointDigest?: string;
45
+ /**
46
+ * A line the relay set for the signature to bind as well (#4697), such as
47
+ * a platform's deploy id and an expiry. chant doesn't read it; the seal
48
+ * signs it. A carried approval keeps the original's.
49
+ */
50
+ binding?: string;
45
51
  /** The line a carried approval came from (#3949): the names and time its seal was made under. */
46
52
  carriedFrom?: { op: string; gate: string; timestamp: string; checkpointDigest?: string };
47
53
  seal?: unknown;
@@ -67,11 +73,14 @@ export function sealedFieldsOf(a: SealedGateApproval): SealedGateApproval {
67
73
  }
68
74
 
69
75
  /**
70
- * The version of a seal over `a` (#3947): 2 when the approval carries a
71
- * checkpoint digest, which the payload signs, and 1 otherwise. `chant approve
72
- * --sign` records 2 on the seal; a seal records no version for 1.
76
+ * The version of a seal over `a` (#3947): 3 when the approval carries a
77
+ * relay's binding (#4697), 2 when it carries a checkpoint digest and no
78
+ * binding, and 1 otherwise. Each signs the lines of the one before plus its
79
+ * own. `chant approve --sign` and `--signature` record 2 and 3 on the seal; a
80
+ * seal records no version for 1.
73
81
  */
74
- export function gateSealVersion(a: Pick<SealedGateApproval, "checkpointDigest" | "carriedFrom">): 1 | 2 {
82
+ export function gateSealVersion(a: Pick<SealedGateApproval, "checkpointDigest" | "carriedFrom" | "binding">): 1 | 2 | 3 {
83
+ if (a.binding !== undefined) return 3;
75
84
  const checkpoint = a.carriedFrom !== undefined ? a.carriedFrom.checkpointDigest : a.checkpointDigest;
76
85
  return checkpoint !== undefined ? 2 : 1;
77
86
  }
@@ -91,14 +100,23 @@ export function gateSealVersion(a: Pick<SealedGateApproval, "checkpointDigest" |
91
100
  * then covered by the seal too, and removing or swapping the digest stops it
92
101
  * verifying. An approval with none signs what a version 1 seal signed.
93
102
  *
103
+ * Seal version 3 (#4697) adds a binding line the relay set, `binding
104
+ * <text>`, after everything else, checkpoint included. A platform puts what
105
+ * it needs the person's signature to cover there too (a deploy id and an
106
+ * expiry); chant records and checks it and reads nothing in it. An approval
107
+ * with no binding signs what a version 1 or 2 seal signed, so those still
108
+ * verify, and an older chant, which leaves the line out, finds a version 3
109
+ * seal doesn't verify and counts nothing for it.
110
+ *
94
111
  * A carried approval (#3949) signs what the line it came from signed: see
95
112
  * {@link sealedFieldsOf}.
96
113
  */
97
114
  export function gateSealPayload(approval: SealedGateApproval): Buffer {
98
115
  const a = sealedFieldsOf(approval);
99
116
  const relay = a.relayedBy !== undefined ? `\nrelayed-by ${a.relayedBy}` : "";
100
- const checkpoint = gateSealVersion(a) === 2 ? `\ncheckpoint ${a.checkpointDigest}` : "";
101
- return Buffer.from(`${a.op}\n${a.gate}\n${a.environment ?? ""}\n${a.planDigest ?? ""}\n${a.resolvedBy}\n${a.timestamp}${relay}${checkpoint}`, "utf-8");
117
+ const checkpoint = a.checkpointDigest !== undefined ? `\ncheckpoint ${a.checkpointDigest}` : "";
118
+ const binding = a.binding !== undefined ? `\nbinding ${a.binding}` : "";
119
+ return Buffer.from(`${a.op}\n${a.gate}\n${a.environment ?? ""}\n${a.planDigest ?? ""}\n${a.resolvedBy}\n${a.timestamp}${relay}${checkpoint}${binding}`, "utf-8");
102
120
  }
103
121
 
104
122
  // ── SSHSIG ───────────────────────────────────────────────────────────────