@futurelastic/colab-handbook 1.20.3 → 1.20.4-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.20.3"
36
+ "version": "1.20.4-rc.2"
37
37
  }
package/tools/colab CHANGED
@@ -1358,7 +1358,11 @@ Refuses, naming each failed condition (all are reported, not just the first):
1358
1358
  format is NAMED in the detail, and the release notes still owe the §6
1359
1359
  judgement on the diff. When nothing was read — no default layout and no
1360
1360
  \`migrations:\` declared, or a declared migration in another format changed —
1361
- the row prints · "not checked" (#670): it refuses nothing, and it is never a ✓
1361
+ the row prints · "not checked" (#670): it refuses nothing, and it is never a ✓.
1362
+ An SQLite table rebuild (CREATE t_new; INSERT INTO t_new SELECT … FROM t; DROP
1363
+ TABLE t; ALTER TABLE t_new RENAME TO t — every row copied, no WHERE/DISTINCT/
1364
+ OR IGNORE) is additive (#709); copied by an explicit column list it prints ·
1365
+ "not checked", since whether the list names every old column is not in the file
1362
1366
  switch-dependencies a colab:switch marker is malformed, or a finished switch needs one that is not
1363
1367
  manifest-version the tag does not equal the version a manifest declares (VERSION, package.json,
1364
1368
  Cargo.toml [package], else [workspace.package] (#620), pyproject.toml
@@ -1414,7 +1418,9 @@ Route deploy-tag-fast (#446) — a deploy: tag repo with the operator's grant an
1414
1418
  release-hold an open issue carries the release-hold label (a human veto)
1415
1419
  migration-grant a migration since the last final with no grant on the version's tracking
1416
1420
  issue — refused; a non-dry run opens "release: vX.Y.Z" if needed and posts the
1417
- one human command (COLAB_HUMAN=1 colab migration-grant <N> --branch vX.Y.Z)
1421
+ one human command (COLAB_HUMAN=1 colab migration-grant <N> --branch vX.Y.Z).
1422
+ That grant is also the person's decision a destructive schema-additive finding
1423
+ needs on this route (#709): with it live, the row passes and names the grant
1418
1424
 
1419
1425
  The bump (without --auto) is release-status's semverSuggestion since the last final tag (candidates skipped): fix ->
1420
1426
  patch, feat -> minor; a breaking change is a minor pre-1.0 and a refusal from 1.0 on.
@@ -1938,7 +1944,7 @@ function cmdReleaseCut(argv) {
1938
1944
  if (num) {
1939
1945
  handoff = releaseCut.migrationHandoff(num, verdict.version);
1940
1946
  commentOnce(repoAbs, num, { state: 'migration-handoff', version: verdict.version },
1941
- `**${verdict.version} carries a database migration**, and route deploy-tag-fast never deploys an ungranted one. The one command, run by a human, lets it ride — the next green run then tags and deploys it:\n\n\`\`\`sh\n${handoff}\n\`\`\``);
1947
+ `**${verdict.version} carries a database migration**, and route deploy-tag-fast never deploys an ungranted one. The one command, run by a human, lets it ride — the next green run then tags and deploys it:\n\n\`\`\`sh\n${handoff}\n\`\`\`${verdict.refusals.some((c) => c.condition === 'schema-additive') ? '\n\nThe schema check also read a **destructive** change (`schema-additive` in the run\'s output). On this route the same grant is the person\'s decision that lets it ride (#709) — read the migration before granting.' : ''}`);
1942
1948
  }
1943
1949
  }
1944
1950
  }
@@ -11961,13 +11967,13 @@ function descriptorHolds(doc) {
11961
11967
  * caller can build the --dry --json `ciGrant`/`ciCure` payloads from the SAME verdicts the prose
11962
11968
  * detail string was built from — see ciGrantPayload/ciCurePayload, below.
11963
11969
  */
11964
- function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk, branch = null) {
11970
+ function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk, branch = null, docsOnlyThunk = null) {
11965
11971
  const name = `${target === trunk ? 'trunk' : 'line'} CI green`;
11966
11972
  const r = readCiVerdict(repoAbs, gh, target, trunk);
11967
11973
  // #678: on a forge the engine map names, the verdict is final — the #482 no-workflow door counts
11968
11974
  // `.github/workflows` and reads the branch through gh, neither of which describes a forge's CI.
11969
11975
  if (forgeCi(repoAbs)) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null };
11970
- const nw = noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch);
11976
+ const nw = noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch, docsOnlyThunk);
11971
11977
  if (nw) return { name, ...nw, grantVerdict: null, cureVerdict: null };
11972
11978
  if (r.final) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null };
11973
11979
  return applyRedTrunkExemptions({ name, ...r.verdict }, target, trunk, r.run.sha, grantThunk, cureThunk);
@@ -11985,14 +11991,27 @@ function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk, branch =
11985
11991
  * real gap (CI not wired, or never started) and still blocks exactly as before. Runs ahead of the
11986
11992
  * #413 grace window too: a run that can never exist is not worth waiting ten minutes for. Returns null when
11987
11993
  * the door does not apply, or a `{ok, class, detail}` verdict when it does.
11994
+ *
11995
+ * #711: a DOCS-ONLY candidate (#606's measurement, secret check included — `docsOnlyThunk` returns
11996
+ * shipDocsOnlyCi's shape, called lazily, only once the trunk is known to have no workflow) passes here
11997
+ * without a run of its own: #606 already ruled that run not required, and a docs-only branch on a
11998
+ * no-workflow trunk can never draw one. Only for a branch on the remote (the same precondition as the
11999
+ * branch-run read). A failed secret check, or a branch that is not docs-only, falls through to the
12000
+ * branch's own run as before.
11988
12001
  */
11989
- function noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch) {
12002
+ function noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch, docsOnlyThunk = null) {
11990
12003
  if (target !== trunk || !branch || !r.run || r.run.status !== 'none' || !r.run.sha || r.verdict.ok) return null;
11991
12004
  if (trunkWorkflowFiles(repoAbs, r.run.sha) !== 0) return null;
11992
12005
  const at = `${trunk}@${shortSha(r.run.sha)}`;
11993
12006
  const own = git.ghRunForSha(repoAbs, branch);
11994
12007
  // Branch not on the remote, or its runs unreadable: nothing to decide with — the prior verdict stands.
12008
+ // #711 keeps this precondition: the docs-only pass below is for a pushed candidate only.
11995
12009
  if (!own) return null;
12010
+ const dc = docsOnlyThunk ? docsOnlyThunk() : null;
12011
+ if (dc && dc.applies && dc.scan && dc.scan.ok) {
12012
+ return { ok: true, class: null,
12013
+ detail: `none — ${at} has no repo-owned workflow, so nothing there can be red (#482); no workflow on trunk; docs-only branch, CI not required (${dc.files} files, secret check clean — #606)${excludedRunsNote(r.run)}` };
12014
+ }
11996
12015
  const ownAt = own.sha ? `${branch}@${shortSha(own.sha)}` : branch;
11997
12016
  if (own && own.status === 'completed' && own.conclusion === 'success') {
11998
12017
  const n = own.runCount == null ? 1 : own.runCount;
@@ -13200,7 +13219,8 @@ function cmdShipDryJson(opts) {
13200
13219
  const gh = isGhUsable(repoAbs);
13201
13220
  const ciResultJson = shipCiCheck(repoAbs, gh, target, trunk,
13202
13221
  (redSha) => shipCiGrants(repoAbs, gh, sess.issues, sess.branch, trunk, redSha),
13203
- (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch);
13222
+ (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch,
13223
+ () => shipDocsOnlyCi(repoAbs, doc, target, sess.branch)); // #711: the #482 door learns the #606 measurement
13204
13224
  ciGrantPayloadVal = ciGrantPayload(ciResultJson);
13205
13225
  ciCurePayloadVal = ciCurePayload(ciResultJson);
13206
13226
  checks.push({ name: ciResultJson.name, ok: ciResultJson.ok, class: ciResultJson.class, detail: ciResultJson.detail });
@@ -14510,7 +14530,8 @@ function cmdShip(argv) {
14510
14530
  // ordinary green-trunk ship makes zero extra `gh` reads for a door nobody needs.
14511
14531
  const ciResult = shipCiCheck(repoAbs, gh, target, trunk,
14512
14532
  (redSha) => shipCiGrants(repoAbs, gh, sess.issues, sess.branch, trunk, redSha),
14513
- (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch);
14533
+ (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch,
14534
+ () => shipDocsOnlyCi(repoAbs, doc, target, sess.branch)); // #711: the #482 door learns the #606 measurement
14514
14535
  const ciOk = ciResult.ok;
14515
14536
  checks.push([ciResult.ok ? '✓' : '✗', ciResult.name, ciResult.detail]);
14516
14537
 
@@ -15052,7 +15073,8 @@ function cmdShip(argv) {
15052
15073
  if (gh || forgeCi(repoAbs)) { // #678: a forge's CI is re-read at B1 exactly as GitHub's is
15053
15074
  const measureB1 = () => shipCiCheck(repoAbs, gh, target, trunk,
15054
15075
  (redSha) => shipCiGrants(repoAbs, gh, sess.issues, sess.branch, trunk, redSha),
15055
- (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch);
15076
+ (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch,
15077
+ () => shipDocsOnlyCi(repoAbs, doc, target, sess.branch)); // #711, same door as the table row
15056
15078
  let ciResultB1 = measureB1();
15057
15079
  // #538: the table admitted this branch through a door (cure or grant) at red sha X, and B1 —
15058
15080
  // seconds later, at the SAME red sha — refused. Nothing the door judges moved (trunk's head is
@@ -675,6 +675,7 @@ function handoffTrackingBody(version) {
675
675
  '',
676
676
  '- The final is automatic on every green head, by the operator\'s grant — but a database migration since the last final never rides an automatic deploy ungranted.',
677
677
  `- **To let it ride:** a human runs \`COLAB_HUMAN=1 colab migration-grant <this issue> --branch ${version}\`; the next green run tags and deploys ${version}.`,
678
+ '- The same grant is the person\'s decision a destructive schema change needs here (a dropped column, a rewritten migration): this route has no hand cut, so the grant is how a person lets one ride (#709). Read the migration first — the grant is the review.',
678
679
  `- **Veto:** add the \`${HOLD_LABEL}\` label to any open issue. While it is present no final is tagged; only a human removes it.`,
679
680
  ].join('\n') + '\n';
680
681
  }
@@ -836,26 +837,109 @@ const SQL_DOWN_MARKER = /^\s*--\s*(\+(migrate|goose)\s+down|migrate:down)\b/i;
836
837
  const SQL_DOWN_FILE = /\.down\.sql$/i;
837
838
 
838
839
  /**
839
- * The first destructive SQL statement outside a Down section — `{ statement, line, inUp }` (1-based
840
- * line in the original file; `inUp` = an Up marker opened the section it sits in) — or null. Skipped
841
- * lines are blanked, not removed, so line numbers stay true and a statement split across lines
842
- * (`DROP\n TABLE`) still matches, as it did when the whole file was read.
840
+ * The SQL a migration runs: every line outside a Down section, `--` comment lines (markers included)
841
+ * blanked — Prisma labels its statements `-- DropIndex`. Skipped lines are blanked, not removed, so
842
+ * line numbers stay true and a statement split across lines (`DROP\n TABLE`) still matches, as it
843
+ * did when the whole file was read. `sections[i]` = the section line i+1 sits in.
843
844
  */
844
- function sqlDestructive(text) {
845
+ function sqlUpText(text) {
845
846
  let section = 'pre';
846
847
  const sections = [];
847
848
  const kept = String(text).split('\n').map((l) => {
848
849
  if (SQL_DOWN_MARKER.test(l)) section = 'down';
849
850
  else if (SQL_UP_MARKER.test(l)) section = 'up';
850
851
  sections.push(section);
851
- // `--` comment lines (markers included) are blanked too: Prisma labels its statements `-- DropIndex`.
852
852
  return section === 'down' || /^\s*--/.test(l) ? '' : l;
853
853
  });
854
- const joined = kept.join('\n');
855
- const m = SQL_DESTRUCTIVE.exec(joined);
856
- if (!m) return null;
857
- const line = joined.slice(0, m.index).split('\n').length;
858
- return { statement: m[0].replace(/\s+/g, ' '), line, inUp: sections[line - 1] === 'up' };
854
+ return { joined: kept.join('\n'), sections };
855
+ }
856
+
857
+ // #709: SQLite cannot widen a CHECK or change a column's type in place, so the documented way
858
+ // (sqlite.org/lang_altertable.html, "other kinds of table schema changes") is a table REBUILD:
859
+ // CREATE TABLE t_new (…); INSERT INTO t_new (…) SELECT … FROM t; DROP TABLE t; ALTER TABLE t_new RENAME TO t;
860
+ // Every row is copied before the drop, so the drop and the rename lose nothing. Read as additive only
861
+ // in that exact shape, and fails CLOSED on anything that could lose a row: a WHERE/JOIN/LIMIT or any
862
+ // other tail after `FROM t`, `SELECT DISTINCT`, `INSERT OR IGNORE|REPLACE` (both skip or merge rows
863
+ // on a stricter constraint), a TEMP table (gone at the end of the session), statements out of order,
864
+ // or an INSERT column list whose length differs from the SELECT list. One thing the file cannot show:
865
+ // whether an explicit SELECT list names EVERY column of `t` — `t` was created by an earlier
866
+ // migration — so such a rebuild is reported `columns: 'listed'` and the verdict says it was not
867
+ // checked; only `SELECT *` (`columns: 'all'`) proves every column is copied.
868
+ const SQL_IDENT = '(?:"[^"]+"|`[^`]+`|\\[[^\\]]+\\]|[A-Za-z_][\\w$]*)';
869
+ const SQL_NAME = `((?:${SQL_IDENT}\\s*\\.\\s*)?${SQL_IDENT})`;
870
+ const SQL_REBUILD = {
871
+ create: new RegExp(`\\bCREATE\\s+(TEMP\\s+|TEMPORARY\\s+)?TABLE\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${SQL_NAME}`, 'gi'),
872
+ insert: new RegExp(`\\bINSERT\\s+INTO\\s+${SQL_NAME}\\s*(?:\\(([^)]*)\\))?\\s*SELECT\\s+([^;]*?)\\s+FROM\\s+${SQL_NAME}\\s*(?=;|$)`, 'gi'),
873
+ drop: new RegExp(`\\bDROP\\s+TABLE\\s+(?:IF\\s+EXISTS\\s+)?${SQL_NAME}`, 'gi'),
874
+ rename: new RegExp(`\\bALTER\\s+TABLE\\s+${SQL_NAME}\\s+(RENAME)\\s+TO\\s+${SQL_NAME}`, 'gi'),
875
+ };
876
+
877
+ /** #709: an SQLite identifier as one comparable key — schema prefix, quoting and case dropped. */
878
+ function sqlKey(name) {
879
+ const parts = String(name).split('.');
880
+ return parts[parts.length - 1].trim().replace(/^["`[]|["`\]]$/g, '').toLowerCase();
881
+ }
882
+
883
+ /** #709: a SELECT or column list split on its top-level commas (a call's own commas stay inside). */
884
+ function sqlListItems(list) {
885
+ const items = [];
886
+ let depth = 0; let cur = '';
887
+ for (const ch of String(list)) {
888
+ if (ch === '(') depth += 1;
889
+ else if (ch === ')') depth -= 1;
890
+ if (ch === ',' && depth === 0) { items.push(cur); cur = ''; } else cur += ch;
891
+ }
892
+ items.push(cur);
893
+ return items.map((x) => x.trim()).filter(Boolean);
894
+ }
895
+
896
+ /**
897
+ * #709: every complete SQLite table rebuild in `joined` (sqlUpText's output) —
898
+ * [{ table, line, columns: 'all'|'listed', drop, rename }]: `drop`/`rename` are the offsets of the
899
+ * `DROP` and `RENAME` keywords SQL_DESTRUCTIVE would otherwise match, `line` the 1-based line of the
900
+ * drop. Pure; a shape it does not recognise is simply not listed, so its statements stay destructive.
901
+ */
902
+ function sqlRebuilds(joined) {
903
+ const all = (re) => [...String(joined).matchAll(new RegExp(re.source, re.flags))];
904
+ const creates = all(SQL_REBUILD.create).filter((m) => !m[1]).map((m) => ({ at: m.index, name: sqlKey(m[2]) }));
905
+ const inserts = all(SQL_REBUILD.insert).map((m) => ({ at: m.index, into: sqlKey(m[1]), cols: m[2], select: m[3], from: sqlKey(m[4]) }));
906
+ const drops = all(SQL_REBUILD.drop).map((m) => ({ at: m.index, name: sqlKey(m[1]) }));
907
+ const renames = all(SQL_REBUILD.rename).map((m) => ({ at: m.index, kw: m.index + m[0].search(/RENAME/i), from: sqlKey(m[1]), to: sqlKey(m[3]) }));
908
+ const out = [];
909
+ for (const d of drops) {
910
+ const t = d.name;
911
+ for (const r of renames) {
912
+ if (r.at < d.at || r.to !== t || r.from === t) continue;
913
+ const fresh = r.from;
914
+ const copy = inserts.find((i) => i.into === fresh && i.from === t && i.at < d.at
915
+ && creates.some((c) => c.name === fresh && c.at < i.at));
916
+ if (!copy) continue;
917
+ const select = copy.select.trim();
918
+ if (/^(DISTINCT|ALL)\b/i.test(select)) continue;
919
+ const star = new RegExp(`^(?:${SQL_IDENT}\\s*\\.\\s*)?\\*$`).test(select);
920
+ if (!star && copy.cols !== undefined && sqlListItems(copy.cols).length !== sqlListItems(select).length) continue;
921
+ out.push({ table: t, line: joined.slice(0, d.at).split('\n').length, columns: star ? 'all' : 'listed', drop: d.at, rename: r.kw });
922
+ break;
923
+ }
924
+ }
925
+ return out;
926
+ }
927
+
928
+ /**
929
+ * The first destructive SQL statement outside a Down section — `{ statement, line, inUp }` (1-based
930
+ * line in the original file; `inUp` = an Up marker opened the section it sits in) — or null. #709: the
931
+ * DROP and RENAME of a complete SQLite table rebuild (sqlRebuilds) are not destructive; any other
932
+ * destructive statement in the same file still is.
933
+ */
934
+ function sqlDestructive(text) {
935
+ const { joined, sections } = sqlUpText(text);
936
+ const exempt = new Set(sqlRebuilds(joined).flatMap((r) => [r.drop, r.rename]));
937
+ for (const m of joined.matchAll(new RegExp(SQL_DESTRUCTIVE.source, 'gi'))) {
938
+ if (exempt.has(m.index)) continue;
939
+ const line = joined.slice(0, m.index).split('\n').length;
940
+ return { statement: m[0].replace(/\s+/g, ' '), line, inUp: sections[line - 1] === 'up' };
941
+ }
942
+ return null;
859
943
  }
860
944
 
861
945
  function laravelUpBody(text) {
@@ -1006,6 +1090,12 @@ function schemaVerdictCore(changes, since, declared, layout, none, missing) {
1006
1090
  .filter((c) => String(c.status || '').charAt(0) === 'A' && c.path.endsWith('.php'))
1007
1091
  .map((c) => ({ name: base(c.path), adds: laravelColumnEvents(laravelUpBody(String(c.content || ''))).filter((e) => e.kind === 'add').map((e) => `${e.table}.${e.column}`) }));
1008
1092
  const addedBefore = (p) => laravelAdds.filter((a) => a.name < base(p)).flatMap((a) => a.adds);
1093
+ // #709: every SQLite table rebuild read as additive, named in the verdict — never silently.
1094
+ const rebuilds = [];
1095
+ // `lineOf` maps a line of `text` to the file's own line — a declared schema file is read by its added lines.
1096
+ const noteRebuilds = (path, text, lineOf = (n) => n) => {
1097
+ for (const r of sqlRebuilds(sqlUpText(text).joined)) rebuilds.push({ path, ...r, line: lineOf(r.line) });
1098
+ };
1009
1099
  for (const c of migrations) {
1010
1100
  const st = String(c.status || '').charAt(0);
1011
1101
  if (st !== 'A') { findings.push(`${c.path}: ${st === 'D' ? 'deleted' : st === 'R' ? 'renamed' : 'edited'} — an existing migration was rewritten`); continue; }
@@ -1017,21 +1107,31 @@ function schemaVerdictCore(changes, since, declared, layout, none, missing) {
1017
1107
  if (SQL_DOWN_FILE.test(c.path)) continue;
1018
1108
  const m = sqlDestructive(text);
1019
1109
  if (m) findings.push(`${c.path}:${m.line}: \`${m.statement}\`${m.inUp ? ' in the Up section' : ''}`);
1110
+ noteRebuilds(c.path, text);
1020
1111
  }
1021
1112
  }
1022
1113
  for (const c of schemaFiles) {
1023
1114
  const f = schemaFileFinding(c);
1024
1115
  if (f) findings.push(f);
1116
+ else if (Array.isArray(c.added)) noteRebuilds(c.path, c.added.map((l) => l.text).join('\n'), (n) => (c.added[n - 1] ? c.added[n - 1].line : '?'));
1117
+ else if (typeof c.content === 'string') noteRebuilds(c.path, c.content);
1025
1118
  }
1026
1119
  if (findings.length) {
1027
- return { ok: false, detail: `destructive schema change since ${since} — a release carrying one is a human's to cut (CONVENTIONS.md §6, Switched epics rule 5): ${findings.join('; ')}` };
1120
+ // `destructive` (#709): a measured destructive finding — not a failed read, not a declaration
1121
+ // contradiction — the one refusal a recorded human decision can clear on route deploy-tag-fast.
1122
+ return { ok: false, destructive: true, detail: `destructive schema change since ${since} — a release carrying one is a human's to cut (CONVENTIONS.md §6, Switched epics rule 5): ${findings.join('; ')}` };
1028
1123
  }
1029
1124
  const read = [
1030
1125
  ...(migrations.length ? [`${migrations.length} migration file(s) added`] : []),
1031
1126
  ...(schemaFiles.length ? [`declared schema file(s) changed (${schemaFiles.map((c) => c.path).join(', ')}), the SQL they added read`] : []),
1032
1127
  ].join(' and ');
1033
- if (unread.length) return notChecked(`${read} since ${since}, none destructive — but ${unreadWhy()}`);
1034
- return { ok: true, detail: `${read} since ${since}, none destructive (${scope})` };
1128
+ const rebuilt = rebuilds.length ? ` — ${rebuilds.length} SQLite table rebuild(s) read as additive (every row copied before the drop): ${rebuilds.map((r) => `${r.path}:${r.line} \`${r.table}\``).join(', ')}` : '';
1129
+ const listed = rebuilds.filter((r) => r.columns === 'listed');
1130
+ if (unread.length) return notChecked(`${read} since ${since}, none destructive${rebuilt} — but ${unreadWhy()}`);
1131
+ if (listed.length) {
1132
+ return notChecked(`${read} since ${since}, none destructive${rebuilt} — but ${listed.map((r) => `\`${r.table}\``).join(', ')} ${listed.length === 1 ? 'is' : 'are'} copied by an explicit column list, and whether it names every column of the old table is not read here (that table was created by an earlier migration); a column the copy leaves out is dropped, so a person reads it before the final — \`SELECT * FROM <table>\` is read as copying every column (#709)`);
1133
+ }
1134
+ return { ok: true, detail: `${read} since ${since}, none destructive${rebuilt} (${scope})` };
1035
1135
  }
1036
1136
 
1037
1137
  /**
@@ -1342,7 +1442,19 @@ function decide(facts) {
1342
1442
  add('on-trunk', false, 'a shallow checkout cannot answer whether the commit is on main (nor find the last final tag) — fetch full history (fetch-depth: 0) and re-run');
1343
1443
  }
1344
1444
 
1345
- for (const [condition, verdict] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
1445
+ // #709: on route deploy-tag-fast no person can cut by hand — the route tags only from the release
1446
+ // workflow, so the deploy runs in the same run — and "a destructive schema change is a person's
1447
+ // decision" (§6 contract item 1) had no act that could make it. The act is the migration grant on
1448
+ // the version's tracking issue: a person, through COLAB_HUMAN=1, bound to this version. A MEASURED
1449
+ // destructive finding (never a failed read, never a declaration contradiction) with that grant live
1450
+ // passes, and the row says whose decision cleared it. Without the grant it refuses exactly as before,
1451
+ // and migration-grant's hand-off below names the one command.
1452
+ let schema = f.schema;
1453
+ const granted = fast && f.migrations && f.migrations.ok && f.migrations.granted;
1454
+ if (schema && !schema.ok && schema.destructive && !schema.unread && granted) {
1455
+ schema = { ok: true, detail: `${schema.detail} — cleared by a person's decision: the migration grant on the tracking issue #${granted}${v.ok ? ` for ${v.version}` : ''} (route deploy-tag-fast, CONVENTIONS.md §6 contract item 4)` };
1456
+ }
1457
+ for (const [condition, verdict] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', schema], ['switch-dependencies', f.switches]]) {
1346
1458
  if (!verdict) add(condition, false, 'not measured', true);
1347
1459
  else {
1348
1460
  add(condition, verdict.ok, verdict.detail, isUnread(verdict));
@@ -1438,6 +1550,7 @@ function tagMessage(verdict, { sha, lastFinal, checkedBy }) {
1438
1550
  }
1439
1551
 
1440
1552
  module.exports = {
1553
+ sqlRebuilds, sqlUpText,
1441
1554
  CONDITIONS, FAST_CONDITIONS, STANDING_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
1442
1555
  isFastRoute, isLibraryRoute, decideManifestVersion, spacingVerdict, holdsVerdict, migrationHandoff,
1443
1556
  parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
@@ -603,7 +603,9 @@ function migrationGrantVerdictCore({ paths, grant, since, layout, none, missing
603
603
  return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };
604
604
  }
605
605
  const list = paths.join(', ');
606
- if (grant && grant.ok) return { ok: true, detail: `${paths.length} migration file(s) since ${since || 'the first commit'} (${list}), granted on the tracking issue #${grant.issue}` };
606
+ // `granted` (#709): the tracking issue whose live grant cleared it — what lets route deploy-tag-fast
607
+ // read the same human decision as clearing a destructive schema change (release-cut.js decide()).
608
+ if (grant && grant.ok) return { ok: true, granted: grant.issue, detail: `${paths.length} migration file(s) since ${since || 'the first commit'} (${list}), granted on the tracking issue #${grant.issue}` };
607
609
  return {
608
610
  ok: false,
609
611
  detail: `${paths.length} migration file(s) since ${since || 'the first commit'} (${list}) and no migration grant on the release${grant && grant.reason ? ` (${grant.reason})` : ''} — an automatically deployed final never carries an ungranted migration; a human finalizes, or grants it first (COLAB_HUMAN=1 colab migration-grant <tracking issue> --branch <version>)`,