@intentius/sql-yodeler 0.8.0 → 0.10.0

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 (163) hide show
  1. package/README.md +15 -7
  2. package/dist/chant/apply.d.ts +6 -0
  3. package/dist/chant/apply.js +6 -2
  4. package/dist/chant/apply.js.map +1 -1
  5. package/dist/chant/build.d.ts +1 -0
  6. package/dist/chant/build.js +5 -0
  7. package/dist/chant/build.js.map +1 -1
  8. package/dist/chant/drift.d.ts +12 -1
  9. package/dist/chant/drift.js +41 -1
  10. package/dist/chant/drift.js.map +1 -1
  11. package/dist/chant/export-name.d.ts +9 -0
  12. package/dist/chant/export-name.js +16 -0
  13. package/dist/chant/export-name.js.map +1 -0
  14. package/dist/chant/runnable.d.ts +1 -1
  15. package/dist/chant/runnable.js +1 -1
  16. package/dist/chant/sql-types.d.ts +19 -0
  17. package/dist/chant/sql-types.js +29 -0
  18. package/dist/chant/sql-types.js.map +1 -0
  19. package/dist/check/flyway.d.ts +67 -0
  20. package/dist/check/flyway.js +106 -0
  21. package/dist/check/flyway.js.map +1 -0
  22. package/dist/check/readers.d.ts +77 -0
  23. package/dist/check/readers.js +270 -0
  24. package/dist/check/readers.js.map +1 -0
  25. package/dist/check/run.d.ts +72 -0
  26. package/dist/check/run.js +243 -0
  27. package/dist/check/run.js.map +1 -0
  28. package/dist/ci/render.d.ts +34 -0
  29. package/dist/ci/render.js +156 -22
  30. package/dist/ci/render.js.map +1 -1
  31. package/dist/cli.js +1 -1
  32. package/dist/cli.js.map +1 -1
  33. package/dist/commands/apply.d.ts +27 -3
  34. package/dist/commands/apply.js +98 -30
  35. package/dist/commands/apply.js.map +1 -1
  36. package/dist/commands/check.d.ts +5 -0
  37. package/dist/commands/check.js +211 -0
  38. package/dist/commands/check.js.map +1 -0
  39. package/dist/commands/config.js +5 -5
  40. package/dist/commands/config.js.map +1 -1
  41. package/dist/commands/drift.js +5 -0
  42. package/dist/commands/drift.js.map +1 -1
  43. package/dist/commands/index.js +2 -0
  44. package/dist/commands/index.js.map +1 -1
  45. package/dist/commands/init.js +15 -6
  46. package/dist/commands/init.js.map +1 -1
  47. package/dist/commands/lint.js +104 -23
  48. package/dist/commands/lint.js.map +1 -1
  49. package/dist/commands/new.js +79 -6
  50. package/dist/commands/new.js.map +1 -1
  51. package/dist/commands/override.js +80 -33
  52. package/dist/commands/override.js.map +1 -1
  53. package/dist/commands/plan.js +62 -30
  54. package/dist/commands/plan.js.map +1 -1
  55. package/dist/commands/revert.js +1 -1
  56. package/dist/config/define.d.ts +28 -2
  57. package/dist/config/define.js.map +1 -1
  58. package/dist/config/load.js +18 -2
  59. package/dist/config/load.js.map +1 -1
  60. package/dist/credentials.d.ts +18 -5
  61. package/dist/credentials.js +29 -11
  62. package/dist/credentials.js.map +1 -1
  63. package/dist/declarative/plan.d.ts +84 -0
  64. package/dist/declarative/plan.js +187 -0
  65. package/dist/declarative/plan.js.map +1 -0
  66. package/dist/declarative/review.d.ts +78 -0
  67. package/dist/declarative/review.js +162 -0
  68. package/dist/declarative/review.js.map +1 -0
  69. package/dist/init/adopt.d.ts +16 -7
  70. package/dist/init/adopt.js +37 -8
  71. package/dist/init/adopt.js.map +1 -1
  72. package/dist/init/baseline.d.ts +2 -1
  73. package/dist/init/baseline.js +3 -3
  74. package/dist/init/baseline.js.map +1 -1
  75. package/dist/init/clickhouse-access.d.ts +29 -10
  76. package/dist/init/clickhouse-access.js +84 -13
  77. package/dist/init/clickhouse-access.js.map +1 -1
  78. package/dist/init/live.d.ts +4 -2
  79. package/dist/init/live.js +8 -3
  80. package/dist/init/live.js.map +1 -1
  81. package/dist/init/unsupported.d.ts +15 -0
  82. package/dist/init/unsupported.js +34 -0
  83. package/dist/init/unsupported.js.map +1 -0
  84. package/dist/lint/annotations.d.ts +1 -1
  85. package/dist/lint/annotations.js +2 -0
  86. package/dist/lint/annotations.js.map +1 -1
  87. package/dist/lint/check.d.ts +8 -1
  88. package/dist/lint/check.js +61 -3
  89. package/dist/lint/check.js.map +1 -1
  90. package/dist/lint/policies.d.ts +22 -0
  91. package/dist/lint/policies.js +47 -0
  92. package/dist/lint/policies.js.map +1 -0
  93. package/dist/lint/report.js +6 -0
  94. package/dist/lint/report.js.map +1 -1
  95. package/dist/lint/schema-checks.d.ts +14 -3
  96. package/dist/lint/schema-checks.js +11 -5
  97. package/dist/lint/schema-checks.js.map +1 -1
  98. package/dist/migrations/create.d.ts +6 -1
  99. package/dist/migrations/create.js +3 -0
  100. package/dist/migrations/create.js.map +1 -1
  101. package/dist/migrations/document.d.ts +6 -0
  102. package/dist/migrations/document.js +1 -0
  103. package/dist/migrations/document.js.map +1 -1
  104. package/dist/migrations/handwritten.d.ts +75 -0
  105. package/dist/migrations/handwritten.js +157 -0
  106. package/dist/migrations/handwritten.js.map +1 -0
  107. package/dist/migrations/index.d.ts +2 -0
  108. package/dist/migrations/index.js +2 -0
  109. package/dist/migrations/index.js.map +1 -1
  110. package/dist/pr/overdue.d.ts +48 -0
  111. package/dist/pr/overdue.js +88 -0
  112. package/dist/pr/overdue.js.map +1 -0
  113. package/dist/pr/part.d.ts +15 -0
  114. package/dist/pr/part.js +30 -0
  115. package/dist/pr/part.js.map +1 -0
  116. package/dist/rebase/index.js +28 -1
  117. package/dist/rebase/index.js.map +1 -1
  118. package/dist/release/index.d.ts +32 -7
  119. package/dist/release/index.js +42 -0
  120. package/dist/release/index.js.map +1 -1
  121. package/dist/replay/replay.d.ts +2 -0
  122. package/dist/replay/replay.js +7 -3
  123. package/dist/replay/replay.js.map +1 -1
  124. package/dist/replay/report.js +3 -1
  125. package/dist/replay/report.js.map +1 -1
  126. package/dist/schemas.d.ts +2 -1
  127. package/dist/schemas.js +1 -0
  128. package/dist/schemas.js.map +1 -1
  129. package/dist/steps/backfill.d.ts +8 -3
  130. package/dist/steps/backfill.js +20 -9
  131. package/dist/steps/backfill.js.map +1 -1
  132. package/dist/steps/index.d.ts +5 -0
  133. package/dist/steps/index.js +10 -0
  134. package/dist/steps/index.js.map +1 -1
  135. package/dist/steps/kinds.d.ts +44 -1
  136. package/dist/steps/kinds.js +50 -1
  137. package/dist/steps/kinds.js.map +1 -1
  138. package/dist/steps/orm-handoff.d.ts +74 -0
  139. package/dist/steps/orm-handoff.js +154 -0
  140. package/dist/steps/orm-handoff.js.map +1 -0
  141. package/dist/testing/run.js +3 -1
  142. package/dist/testing/run.js.map +1 -1
  143. package/dist/versioned/approval.d.ts +27 -7
  144. package/dist/versioned/approval.js +69 -18
  145. package/dist/versioned/approval.js.map +1 -1
  146. package/dist/versioned/engine.js +31 -2
  147. package/dist/versioned/engine.js.map +1 -1
  148. package/dist/versioned/op.d.ts +20 -3
  149. package/dist/versioned/op.js +12 -6
  150. package/dist/versioned/op.js.map +1 -1
  151. package/dist/versioned/policy.d.ts +2 -0
  152. package/dist/versioned/policy.js +2 -2
  153. package/dist/versioned/policy.js.map +1 -1
  154. package/dist/versioned/state.js +5 -0
  155. package/dist/versioned/state.js.map +1 -1
  156. package/package.json +21 -9
  157. package/schemas/apply.schema.json +36 -2
  158. package/schemas/check.schema.json +78 -0
  159. package/schemas/drift.schema.json +1 -0
  160. package/schemas/init.schema.json +1 -0
  161. package/schemas/lint.schema.json +9 -1
  162. package/schemas/new.schema.json +1 -0
  163. package/schemas/plan.schema.json +33 -0
@@ -2,6 +2,7 @@ import type { Command } from "../command.js";
2
2
  import { type Project, type SqlDialect } from "../project.js";
3
3
  import type { CheckOutcome, Migration } from "../migrations/index.js";
4
4
  import { type ServerInfo } from "../server.js";
5
+ import type { ApprovalMode } from "../config/define.js";
5
6
  import { type WavePlanFile } from "../waves/index.js";
6
7
  import { type MigrateOpRef, type VersionedEnv } from "../versioned/index.js";
7
8
  import type { ExecuteResult } from "../versioned/engine.js";
@@ -14,23 +15,37 @@ declare function movedSinceApproval(project: Project, venv: VersionedEnv, ordere
14
15
  at: string;
15
16
  digest: string | undefined;
16
17
  };
17
- approved: string;
18
18
  by: string;
19
19
  at: string;
20
20
  confirmed: boolean;
21
21
  changes: never[];
22
+ now?: string;
23
+ approved: string;
22
24
  };
23
25
  line: string;
24
26
  } | {
25
27
  moved: {
26
- approved: string;
27
28
  by: string;
28
29
  at: string;
29
30
  confirmed: boolean;
30
31
  changes: import("../versioned/explain.js").Moved[];
32
+ now?: string;
33
+ approved: string;
31
34
  };
32
35
  line: string;
33
36
  } | undefined>;
37
+ /**
38
+ * The commands that approve `digest` at the migrations Op's gate: from chant's
39
+ * output when it printed one, else made here (#273), so `--json` always says
40
+ * what to run next when there is a plan to approve.
41
+ */
42
+ export declare function approveCommandsFor(run: {
43
+ chantApprove?: string;
44
+ planDigest?: string;
45
+ }, env: string, op: MigrateOpRef, digest: string | undefined, mode: ApprovalMode): {
46
+ approve?: string;
47
+ chantApprove?: string;
48
+ };
34
49
  /** What a versioned run did, beyond the status it reports. */
35
50
  export type VersionedOutcome = {
36
51
  status: "planned" | "unchanged";
@@ -64,16 +79,25 @@ export type VersionedOutcome = {
64
79
  op: string;
65
80
  exitCode: number;
66
81
  chantExitCode: number;
82
+ moved?: NonNullable<Awaited<ReturnType<typeof movedSinceApproval>>>["moved"];
83
+ approve?: string;
84
+ chantApprove?: string;
67
85
  } | {
68
86
  status: "applied";
69
87
  op: string;
70
88
  appliedNow: string[];
89
+ resumed?: {
90
+ gate: string;
91
+ run: string;
92
+ checkpoint: string;
93
+ };
71
94
  };
72
95
  /** What a declarative run (the ApplyOp) did; `plan` is the plan before the run. */
73
96
  export type DeclarativeOutcome = {
74
97
  plan: Record<string, unknown>;
98
+ policy?: RuleResult[];
75
99
  } & ({
76
- status: "refused" | "unchanged" | "applied";
100
+ status: "refused" | "denied" | "unchanged" | "applied";
77
101
  } | {
78
102
  status: "gated";
79
103
  gate: string;
@@ -21,9 +21,11 @@ import { baseEnvironment, tenantTarget } from "../tenants/target.js";
21
21
  import { enforcePromotion, forecastWave, planWave, RECORD_PLANS_ENV, readWavePlan, verifyWaveDecision, WavePlanMoved, WAVES_SPEC_FILE, writeWavePlan } from "../waves/index.js";
22
22
  import { applySlot, slotTenants, splitSlot, writeSlotPlan } from "../tenants/wave.js";
23
23
  import { ALLOW_OUT_OF_ORDER_ENV, APPROVED_PLAN_ENV, checksDue, checksRefusal, describeResults, judgePlan, judgeRevert, overrideSourceAt, overrideSubject, policyRefusal, spendOverride, runChecks, currentDigest, currentRevert, executeApply, executeRevert, revertFromEnv, findMigrateOp, gitLedger, verifyApproval, hasMigrations, inspect, readChain, recordStepExit, closeVersioned, openVersioned, renderStatus, runMigrateOp, selectToApply, statusJson, statusReport, } from "../versioned/index.js";
24
+ import { declarativeDigest } from "../declarative/review.js";
25
+ import { declarativeOverrideSource, judgeDeclarative } from "../declarative/plan.js";
24
26
  import { BASELINE_ENV } from "../versioned/op.js";
25
27
  import { baselineFromEnv, executeBaseline, planBaseline, projectBaseline } from "../init/second.js";
26
- import { appliedHead, recordReleaseLines } from "../release/index.js";
28
+ import { appliedHead, recordReleaseLines, RELEASE_ENV, releaseToApply } from "../release/index.js";
27
29
  /** When the gate's newest approval does not hold: what moved since (or that approval was asked for again), in one line. */
28
30
  async function movedSinceApproval(project, venv, ordered, op, digest) {
29
31
  try {
@@ -32,13 +34,13 @@ async function movedSinceApproval(project, venv, ordered, op, digest) {
32
34
  return undefined;
33
35
  if (latest.sameDigest) {
34
36
  return {
35
- moved: { approved: latest.digest, by: latest.by, at: latest.at, confirmed: true, changes: [], ...(latest.askedAgain ? { askedAgain: latest.askedAgain } : {}) },
37
+ moved: { approved: latest.digest, ...(digest ? { now: digest } : {}), by: latest.by, at: latest.at, confirmed: true, changes: [], ...(latest.askedAgain ? { askedAgain: latest.askedAgain } : {}) },
36
38
  line: `Nothing was applied. The approval of ${latest.digest} (by ${latest.by} at ${latest.at}) ${askedAgainLine(latest)}.`,
37
39
  };
38
40
  }
39
41
  const moved = await explainAgainst(venv, ordered, { approvedDigest: latest.digest, approvedAt: latest.at });
40
42
  return {
41
- moved: { approved: latest.digest, by: latest.by, at: latest.at, confirmed: moved.confirmed, changes: moved.changes },
43
+ moved: { approved: latest.digest, ...(digest ? { now: digest } : {}), by: latest.by, at: latest.at, confirmed: moved.confirmed, changes: moved.changes },
42
44
  line: `Nothing was applied. The approval of ${latest.digest} (by ${latest.by} at ${latest.at}) does not hold: the plan moved since. ${moved.confirmed ? "What moved" : "What moved, as far as yodel can tell"}: ${describeMove(moved)}.`,
43
45
  };
44
46
  }
@@ -46,6 +48,17 @@ async function movedSinceApproval(project, venv, ordered, op, digest) {
46
48
  return undefined;
47
49
  }
48
50
  }
51
+ /**
52
+ * The commands that approve `digest` at the migrations Op's gate: from chant's
53
+ * output when it printed one, else made here (#273), so `--json` always says
54
+ * what to run next when there is a plan to approve.
55
+ */
56
+ export function approveCommandsFor(run, env, op, digest, mode) {
57
+ const d = run.planDigest ?? digest;
58
+ if (run.chantApprove)
59
+ return gatedCommands(run, env, mode);
60
+ return d ? gatedCommands({ chantApprove: `chant approve ${op.name} ${op.gate} --plan ${d}`, planDigest: d }, env, mode) : {};
61
+ }
49
62
  /** The document `yodel apply --json` prints (schemas/apply.schema.json). */
50
63
  export function applyJson(doc) {
51
64
  if (doc.mode === "versioned")
@@ -56,7 +69,7 @@ export function applyJson(doc) {
56
69
  return { ...doc.plan };
57
70
  return { environment: doc.environment, dialect: doc.dialect, ...(doc.server ? { server: doc.server } : {}), op: doc.op, ...doc.outcome };
58
71
  }
59
- const usage = "usage: yodel apply <env> [--json] [--dir <project>] [--op <name>] [--allow-out-of-order] [--plan] [--lock-wait <duration>] [--stand-down]";
72
+ const usage = "usage: yodel apply <env> [--json] [--dir <project>] [--op <name>] [--allow-out-of-order] [--plan] [--lock-wait <duration>] [--stand-down] [--release <ref>]";
60
73
  const waveModes = ["wave-plan", "wave-apply", "step-sql"];
61
74
  const help = `${usage}
62
75
 
@@ -110,12 +123,18 @@ Two paths, chosen by the project:
110
123
 
111
124
  - Declarative: no migrations. Plans the declared schema against the live
112
125
  database, then runs the project's ApplyOp for the environment behind its
113
- plan-bound gate.
126
+ plan-bound gate. The policy (yodel.config.ts policy, at the base commit)
127
+ judges the plan first: a rule that denies it refuses (exit 4) before the
128
+ ApplyOp runs, unless an override counts for exactly these changes (yodel
129
+ override <env>), which is spent once the ApplyOp applies. Waves, tenant
130
+ sets, --allow-out-of-order and the lock read a history of migrations, so
131
+ they are for the versioned path (docs/workflows.md lists what each path
132
+ has).
114
133
 
115
134
  Both paths write. For a profile made with credentials(), yodel apply runs
116
- as the writer only under YODEL_CREDENTIALS=writer or writer:<env>; as the
135
+ as the writer only under YODEL_ROLE=writer or writer:<env>; as the
117
136
  reader it refuses before the gate (exit 4), and the command it prints to
118
- run again after a gate stop carries YODEL_CREDENTIALS=writer:<env>. A server
137
+ run again after a gate stop carries YODEL_ROLE=writer:<env>. A server
119
138
  that refuses a write for want of a privilege is told in one line naming the
120
139
  user (exit 4).
121
140
 
@@ -135,6 +154,11 @@ Options:
135
154
  that commit's own apply applies this environment.
136
155
  Asked before the lock and while waiting for it. Also
137
156
  YODEL_STAND_DOWN=1
157
+ --release <ref> the apply is made from a chant release (chant release
158
+ cut), named by its digest or label: the checkout must
159
+ be at the commit the release was cut at, and the
160
+ release record names it (releaseDigest). Also
161
+ ${RELEASE_ENV}=<ref>
138
162
  -C, --dir <dir> the project directory (default: the working directory)
139
163
 
140
164
  The migrations Op runs two steps of its own, not for direct use:
@@ -173,8 +197,9 @@ Exit codes:
173
197
  policy rule that denies the plan with no override, or a pending
174
198
  migration the environment this one requires (yodel.config.ts
175
199
  waves[].requires, default the wave before) does not record as applied
176
- with the same checksum. Either path: the run holds <env>'s reader
177
- (YODEL_CREDENTIALS is not writer or writer:<env>), which refuses before
200
+ with the same checksum. Declarative: a policy rule that denies the
201
+ plan with no override. Either path: the run holds <env>'s reader
202
+ (YODEL_ROLE is not writer or writer:<env>), which refuses before
178
203
  the gate, or the server refused the user a privilege
179
204
  5 versioned: another apply holds the lock (after --lock-wait, if given)
180
205
  1 anything else failed: a statement (the history records where; rerun to
@@ -197,6 +222,7 @@ function parseApplyArgs(args) {
197
222
  execute: { type: "boolean" },
198
223
  "lock-wait": { type: "string" },
199
224
  "stand-down": { type: "boolean" },
225
+ release: { type: "string" },
200
226
  "wave-plan": { type: "string" },
201
227
  "wave-apply": { type: "string" },
202
228
  spec: { type: "string" },
@@ -235,6 +261,7 @@ function parseApplyArgs(args) {
235
261
  waveApply: str("wave-apply"),
236
262
  stepArgv: str("step-sql") !== undefined ? ["yodel", "apply", ...args] : undefined,
237
263
  spec: str("spec") ?? WAVES_SPEC_FILE,
264
+ release: str("release") ?? (process.env[RELEASE_ENV] || undefined),
238
265
  };
239
266
  }
240
267
  /** `yodel apply <env>`; the exit codes are in `help`. */
@@ -254,6 +281,9 @@ export const apply = {
254
281
  const asReader = writes ? readerRefusal(profile, runnable(command, project.dir)) : undefined;
255
282
  if (asReader)
256
283
  throw new YodelError(asReader, EXIT_REFUSED);
284
+ // An apply made from a chant release (#277) names it; one at another commit than the release's is refused before anything runs.
285
+ if (writes && a.release !== undefined)
286
+ a.releaseDigest = await releaseToApply(project.dir, a.release);
257
287
  try {
258
288
  return await applyIn(project, a, args, io);
259
289
  }
@@ -282,7 +312,7 @@ async function applyIn(project, a, args, io) {
282
312
  if (hasMigrations(project))
283
313
  return versionedApply(project, env, a, io);
284
314
  if (a.plan || a.digest || a.execute || a.allowOutOfOrder || a.lockWaitMs !== undefined || args.includes("--stand-down") || a.wavePlan !== undefined || a.waveApply !== undefined) {
285
- throw new YodelError(`--plan, --digest, --execute, --wave-plan, --wave-apply, --allow-out-of-order, --lock-wait and --stand-down are for versioned migrations, and ${project.dir} has no migrations/ directory with a migration`);
315
+ throw new YodelError(`--plan, --digest, --execute, --wave-plan, --wave-apply, --allow-out-of-order, --lock-wait and --stand-down are for versioned migrations, and ${project.dir} has no migrations/ directory with a migration (see docs/workflows.md for what each path has)`);
286
316
  }
287
317
  const refusal = declarativeRefusal(project, env.name);
288
318
  if (refusal)
@@ -387,17 +417,17 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
387
417
  throw new YodelError(`--execute records a baseline only under the plan its Op's gate approved, and ${APPROVED_PLAN_ENV} is not set; run yodel init --baseline ${env.name}`);
388
418
  const op = await findMigrateOp(project, env, a.op);
389
419
  const ledger = await migrationsLedger(project, env.name, io);
390
- let approver;
420
+ let admittedBy = {};
391
421
  await executeBaseline(project, env, venv, baseline, {
392
422
  approvedDigest: approved,
393
423
  approve: async (digest) => {
394
424
  const by = await verifyApproval(ledger, op, digest);
395
- approver = by.resolvedBy;
425
+ admittedBy = { approver: by.approver, admission: by.admission };
396
426
  io.err(`approval: ${op.name} / ${op.gate} for ${digest}, by ${by.resolvedBy} at ${by.timestamp}\n`);
397
427
  },
398
428
  log: (l) => { io.err(`${l}\n`); },
399
429
  });
400
- await recordApplied(project, env, venv, ordered, io, approver);
430
+ await recordApplied(project, env, venv, ordered, io, { ...admittedBy, releaseDigest: a.releaseDigest });
401
431
  io.out(`Recorded: ${baseline.id}, as ${env.name}'s baseline\n`);
402
432
  return 0;
403
433
  }
@@ -413,7 +443,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
413
443
  throw new YodelError(`--execute reverts only the plan its Op's gate approved, and ${APPROVED_PLAN_ENV} is not set; run yodel revert ${env.name} ${revert.id}`);
414
444
  const op = await findMigrateOp(project, env, a.op);
415
445
  const ledger = await migrationsLedger(project, env.name, io);
416
- let approver;
446
+ let admittedBy = {};
417
447
  // The policy over the revert (#97), as the base commit has it (#73), as yodel revert judged it before the gate.
418
448
  const { policy: basePolicy, note: policyNote } = await policyAtBase(project);
419
449
  if (policyNote)
@@ -425,7 +455,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
425
455
  ...(a.lockWaitMs !== undefined ? { lockWaitMs: a.lockWaitMs } : {}),
426
456
  approve: async (digest) => {
427
457
  const by = await verifyApproval(ledger, op, digest);
428
- approver = by.resolvedBy;
458
+ admittedBy = { approver: by.approver, admission: by.admission };
429
459
  io.err(`approval: ${op.name} / ${op.gate} for ${digest}, by ${by.resolvedBy} at ${by.timestamp}\n`);
430
460
  },
431
461
  ...(basePolicy
@@ -451,7 +481,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
451
481
  : {}),
452
482
  log: (l) => { io.err(`${l}\n`); },
453
483
  });
454
- await recordApplied(project, env, venv, ordered, io, approver);
484
+ await recordApplied(project, env, venv, ordered, io, { ...admittedBy, releaseDigest: a.releaseDigest });
455
485
  io.out(`Reverted: ${plan.migration.id}, back to ${plan.to ?? "an empty schema"}\n`);
456
486
  return 0;
457
487
  }
@@ -558,7 +588,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
558
588
  // An apply that changed nothing ran no step, and tells chant so: a step command runs once per apply that changes the schema, not once per push (#206).
559
589
  await hooks.skipped(result.stoodDown ?? "nothing to apply");
560
590
  if (result.applied.length > 0)
561
- await recordApplied(project, env, venv, ordered, io, wave?.review?.approvers.join(", "));
591
+ await recordApplied(project, env, venv, ordered, io, { approver: wave?.review?.approvers.join(", "), releaseDigest: a.releaseDigest });
562
592
  if (a.json)
563
593
  io.out(`${JSON.stringify(applyJson({ mode: "execute", environment: env.name, planDigest: planned.migrations, wavePlanDigest: planned.planDigest, result }), null, 2)}\n`);
564
594
  else
@@ -579,7 +609,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
579
609
  if (steps.note)
580
610
  io.err(`${steps.note}\n`);
581
611
  let before = [];
582
- let approver;
612
+ let admittedBy = {};
583
613
  // The steps (#64) as stage hooks (#206), read at base; the Op's approval, checked under the lock before they run, lets a held one through.
584
614
  const hooksFile = stepsHooksFile(steps.steps, env.name, { approved: true, ...(steps.sha ? { base: steps.sha } : {}) });
585
615
  const hooks = applyHooks(project, venv, env, () => hooksFile, io);
@@ -594,7 +624,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
594
624
  // Under the lock: every pending migration ran first where this environment requires (exit 4 otherwise).
595
625
  await enforcePromotion(project, env.name, ordered, (await inspect(venv, ordered)).status.pending);
596
626
  const by = await verifyApproval(ledger, op, digest);
597
- approver = by.resolvedBy;
627
+ admittedBy = { approver: by.approver, admission: by.admission };
598
628
  io.err(`approval: ${op.name} / ${op.gate} for ${digest}, by ${by.resolvedBy} at ${by.timestamp}${by.signer !== undefined ? `, sealed by ${by.signer}` : ""}\n`);
599
629
  // The before steps (#64), under the lock: one that fails refuses; a held one is let through by the Op's approval, which every run of it asks for.
600
630
  before = await hooks.before();
@@ -624,7 +654,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
624
654
  : {}),
625
655
  });
626
656
  if (result.applied.length > 0)
627
- await recordApplied(project, env, venv, ordered, io, approver);
657
+ await recordApplied(project, env, venv, ordered, io, { ...admittedBy, releaseDigest: a.releaseDigest });
628
658
  if (a.json)
629
659
  io.out(`${JSON.stringify(applyJson({ mode: "execute", environment: env.name, planDigest: approved, result }), null, 2)}\n`);
630
660
  else
@@ -743,6 +773,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
743
773
  ...process.env,
744
774
  ...(a.lockWaitMs !== undefined ? { [LOCK_WAIT_ENV]: `${String(a.lockWaitMs)}ms` } : {}),
745
775
  ...(a.standDown ? { [STAND_DOWN_ENV]: "1" } : {}),
776
+ ...(a.releaseDigest ? { [RELEASE_ENV]: a.releaseDigest } : {}),
746
777
  };
747
778
  const run = await runMigrateOp(project, op, { allowOutOfOrder: a.allowOutOfOrder, env: childEnv, onOutput: (t) => { io.err(t); } });
748
779
  if (run.status === "gated") {
@@ -753,7 +784,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
753
784
  io.out(`\n${op.name} is waiting at gate "${op.gate}" for approval of this plan${run.planDigest ? ` (${run.planDigest})` : ""}.\n`);
754
785
  }
755
786
  // A sealed gate (#48) counts only a sealed approval, which --execute checks.
756
- const commands = gatedCommands(run, env.name, (await migrationsApprovalAtBase(project, env.name)).mode);
787
+ const commands = approveCommandsFor(run, env.name, op, report.digest, (await migrationsApprovalAtBase(project, env.name)).mode);
757
788
  if (!a.json && commands.approve) {
758
789
  io.out(`Approve it at a terminal with:\n ${runnable(commands.approve, project.dir)}\n` +
759
790
  `which shows the plan and asks you first; then run ${runnableAsWriter(`yodel apply ${env.name}`, project.dir, env.profile)} again.\n`);
@@ -768,7 +799,12 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
768
799
  io.err(`yodel apply: chant run ${op.name} failed (exit ${String(run.code)})${run.stepExit ? `: its Apply step, yodel apply ${env.name} --execute, exited ${String(run.stepExit)}` : ""}\n`);
769
800
  io.out(`\n${renderStatus(after)}`);
770
801
  }
771
- outcome.doc = applyJson({ mode: "versioned", report: after, outcome: { status: "failed", op: op.name, exitCode: code, chantExitCode: run.code } });
802
+ // The plan moved under the lock since it was approved (#273): what moved, and the commands that approve the plan as it is now.
803
+ const stale = after.digest ? await movedSinceApproval(project, venv, ordered, op, after.digest) : undefined;
804
+ const again = stale ? approveCommandsFor({}, env.name, op, after.digest, (await migrationsApprovalAtBase(project, env.name)).mode) : {};
805
+ if (stale && !a.json && again.approve)
806
+ io.out(`\n${stale.line}\nApprove the plan as it is now with:\n ${runnable(again.approve, project.dir)}\nthen run ${runnableAsWriter(`yodel apply ${env.name}`, project.dir, env.profile)} again.\n`);
807
+ outcome.doc = applyJson({ mode: "versioned", report: after, outcome: { status: "failed", op: op.name, exitCode: code, chantExitCode: run.code, ...(stale ? { moved: stale.moved } : {}), ...again } });
772
808
  if (a.json)
773
809
  io.out(`${JSON.stringify(outcome.doc, null, 2)}\n`);
774
810
  return code;
@@ -781,7 +817,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
781
817
  return emit({ status: "stood-down", stoodDown: stoodLate, op: op.name }, 0);
782
818
  }
783
819
  if (a.json) {
784
- io.out(`${JSON.stringify(applyJson({ mode: "versioned", report: after, outcome: { status: "applied", op: op.name, appliedNow: report.status.pending.map((p) => p.id) } }), null, 2)}\n`);
820
+ io.out(`${JSON.stringify(applyJson({ mode: "versioned", report: after, outcome: { status: "applied", op: op.name, appliedNow: report.status.pending.map((p) => p.id), ...(run.resumed ? { resumed: run.resumed } : {}) } }), null, 2)}\n`);
785
821
  }
786
822
  else {
787
823
  io.out(`\nApplied: ${report.status.pending.map((p) => p.id).join(", ")}.\n`);
@@ -822,11 +858,41 @@ async function declarativeRun(project, env, a, io, op, report, setServer) {
822
858
  io.err(`yodel apply: refused: ${unreadable.length > 0 ? `${unreadable.map((u) => u.object).join(", ")} could not be read` : `${String(before.refused.length)} change(s) need their own Op`}; nothing was applied\n`);
823
859
  return report({ status: "refused", plan: planJson(before) }, PLAN_NEEDS_OP);
824
860
  }
825
- if (declaredChanges(before, build).length === 0) {
861
+ const changes = declaredChanges(before, build);
862
+ if (changes.length === 0) {
826
863
  if (!json)
827
864
  io.out(`${env.name} already matches the declared schema; nothing to apply.\n`);
828
865
  return report({ status: "unchanged", plan: planJson(before) }, 0);
829
866
  }
867
+ // The policy as the base commit has it (#73, #249), before the gate: a plan a rule denies, with no override, never reaches it.
868
+ const basePolicy = await policyAtBase(project);
869
+ if (basePolicy.note)
870
+ io.err(`${basePolicy.note}\n`);
871
+ const digest = await declarativeDigest(env.name, project.dialect, changes);
872
+ let standing;
873
+ const policy = await judgeDeclarative({
874
+ policy: basePolicy.policy,
875
+ environment: env.name,
876
+ dialect: project.dialect,
877
+ changes,
878
+ digest,
879
+ ledger: () => declarativeOverrideSource(project, env.name, op.name),
880
+ // Spent once the ApplyOp applies, not here: a run that stops at the gate has applied nothing under it.
881
+ spend: (o) => {
882
+ standing = o;
883
+ return Promise.resolve();
884
+ },
885
+ });
886
+ const withPolicy = policy.length > 0 ? { policy } : {};
887
+ if (!json)
888
+ for (const l of describeResults(policy))
889
+ io.out(`${l}\n`);
890
+ const denied = policyRefusal(policy, env.name, digest, "before the gate");
891
+ if (denied) {
892
+ if (!json)
893
+ io.err(`yodel apply: ${denied.message}\n`);
894
+ return report({ status: "denied", plan: planJson(before), ...withPolicy }, EXIT_REFUSED);
895
+ }
830
896
  if (!json)
831
897
  io.out(`\nRunning ${op.name} (${op.filePath})\n`);
832
898
  const run = await runApplyOp(project, op, { onOutput: (t) => { io.err(t); } });
@@ -837,12 +903,12 @@ async function declarativeRun(project, env, a, io, op, report, setServer) {
837
903
  if (commands.approve)
838
904
  io.out(`Approve it at a terminal with:\n ${runnable(commands.approve, project.dir)}\nwhich shows the plan and asks you first; then run ${runnableAsWriter(`yodel apply ${env.name}`, project.dir, env.profile)} again.\n`);
839
905
  }
840
- return report({ status: "gated", gate: op.gate, ...commands, ...(run.planDigest ? { planDigest: run.planDigest } : {}), plan: planJson(before) }, GATED);
906
+ return report({ status: "gated", gate: op.gate, ...commands, ...(run.planDigest ? { planDigest: run.planDigest } : {}), plan: planJson(before), ...withPolicy }, GATED);
841
907
  }
842
908
  if (run.status === "failed") {
843
909
  if (!json)
844
910
  io.err(`yodel apply: chant run ${op.name} failed (exit ${String(run.code)})\n`);
845
- return report({ status: "failed", exitCode: run.code, plan: planJson(before) }, 1);
911
+ return report({ status: "failed", exitCode: run.code, plan: planJson(before), ...withPolicy }, 1);
846
912
  }
847
913
  // The Op completed: check the server now matches, so a change the applier did not attempt is not reported as applied.
848
914
  const after = await planEnvironment(project, env, build);
@@ -850,22 +916,24 @@ async function declarativeRun(project, env, a, io, op, report, setServer) {
850
916
  if (remaining.length > 0) {
851
917
  if (!json)
852
918
  io.err(`yodel apply: ${op.name} completed but ${String(remaining.length)} change(s) to declared objects are still planned (a drop the Op's delete mode withholds, or a change it did not attempt):\n${await renderPlan(after, `Plan for ${env.name} after apply`)}\n`);
853
- return report({ status: "incomplete", plan: planJson(before), remaining: planJson(after) }, 1);
919
+ return report({ status: "incomplete", plan: planJson(before), remaining: planJson(after), ...withPolicy }, 1);
854
920
  }
921
+ if (standing)
922
+ await spendOverride(project.dir, standing, (l) => { io.err(`yodel apply: ${l}\n`); });
855
923
  for (const line of await recordReleaseLines(project, env, build.output))
856
924
  io.err(`${line}\n`);
857
925
  if (!json)
858
926
  io.out(`\nApplied: ${env.name} matches the declared schema.\n`);
859
- return report({ status: "applied", plan: planJson(before) }, 0);
927
+ return report({ status: "applied", plan: planJson(before), ...withPolicy }, 0);
860
928
  }
861
929
  finally {
862
930
  build.dispose();
863
931
  }
864
932
  }
865
933
  /** Records the schema `env` holds now on chant's release ledger (#208), told on stderr. */
866
- async function recordApplied(project, env, venv, ordered, io, approver) {
934
+ async function recordApplied(project, env, venv, ordered, io, facts) {
867
935
  const { status } = await inspect(venv, ordered);
868
- const lines = await recordReleaseLines(project, env, appliedHead(ordered, status)?.document.schema, approver ? { approver } : {});
936
+ const lines = await recordReleaseLines(project, env, appliedHead(ordered, status)?.document.schema, facts);
869
937
  for (const line of lines)
870
938
  io.err(`${line}\n`);
871
939
  }