@futurelastic/colab-handbook 1.18.0-rc.10 → 1.18.0-rc.11

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/audit/audit.mjs CHANGED
@@ -269,6 +269,9 @@ function parseScalarValue(raw) {
269
269
  const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds", "contention"]); // owner: #394 · gate: #410 · thresholds: #560 · contention: #630
270
270
  // The one map whose pairs may hold an INLINE list (`coupled: [a, b]`) — still one level, still no block list (#630).
271
271
  const LIST_IN_MAP_KEYS = new Set(["contention"]);
272
+ // A key whose empty value may open EITHER a block list or a one-level map: `migrations:` is a list of
273
+ // paths, or the `none: <reason>` block (#672). The two line shapes cannot be mistaken for each other.
274
+ const LIST_OR_MAP_KEYS = new Set(["migrations"]);
272
275
 
273
276
  function parseFlatYaml(text) {
274
277
  const out = {};
@@ -340,6 +343,7 @@ function parseFlatYaml(text) {
340
343
  if (trimmed === "") {
341
344
  if (NESTED_MAP_KEYS.has(key)) mapKey = key;
342
345
  else listKey = key;
346
+ if (LIST_OR_MAP_KEYS.has(key)) mapKey = key;
343
347
  }
344
348
  });
345
349
  return { data: out, problems };
@@ -1426,6 +1430,14 @@ function auditRepoInner(target, ctx) {
1426
1430
  migCfg.problems.forEach((p) => fail(p));
1427
1431
  migCfg.notes.forEach((p) => warn(p));
1428
1432
  const migFiles = src.migrationDirFiles();
1433
+ // #672's guard, where the declaration is read: `migrations: none` beside a Laravel or Prisma
1434
+ // migrations directory is a contradiction, and every later cut refuses it too (release-cut.js
1435
+ // schemaVerdict, release-finalize.js migrationGrantVerdict). Local-only, like the rule below.
1436
+ if (migFiles && migCfg.none) {
1437
+ const dirsOf = migFiles.map((f) => f.split("/").slice(0, -1).map((_, i, a) => a.slice(0, i + 1).join("/"))).flat();
1438
+ const why = migrationPaths.noneContradiction(migCfg.none, migrationPaths.defaultLayoutDirs([...new Set(dirsOf)]));
1439
+ if (why) fail(`migrations: ${why}`);
1440
+ }
1429
1441
  if (migFiles) {
1430
1442
  const undeclared = migrationPaths.undeclaredMigrationDirs(migFiles, migCfg.paths);
1431
1443
  if (undeclared.length) {
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.18.0-rc.10"
36
+ "version": "1.18.0-rc.11"
37
37
  }
package/tools/colab CHANGED
@@ -1486,10 +1486,16 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
1486
1486
  // matched (migration-paths.js isMigrationPath)? Without one and with nothing declared, the check
1487
1487
  // read nothing: "not checked", never a ✓. null = the tree could not be read, never "absent".
1488
1488
  const layoutR = git.git(['ls-tree', '-r', '-d', '--name-only', sha], repoAbs);
1489
- const layout = layoutR.ok ? layoutR.stdout.split('\n').some((d) => d && migrationPaths.isMigrationPath(`${d}/`, [])) : null;
1489
+ const layoutDirs = layoutR.ok ? migrationPaths.defaultLayoutDirs(layoutR.stdout.split('\n')) : null;
1490
+ const layout = layoutDirs ? layoutDirs.length > 0 : null;
1491
+ // #672: `migrations: none` counts only as committed AT THE CANDIDATE — never the disk copy, which on
1492
+ // a finalize is trunk's head, not what ships — and only where nothing declares a layout (a declared
1493
+ // path anywhere wins: the gate then sees more, never less). The default-layout guard is the verdicts'.
1494
+ const noneAt = declared.length ? null : migrationPaths.parseMigrationPaths(projectDocAt(repoAbs, sha)).none;
1495
+ const none = noneAt ? { ...noneAt, dirs: layoutDirs || [] } : null;
1490
1496
  const schema = changes === null
1491
1497
  ? { ok: false, unread: true, detail: 'git diff failed — schema changes cannot be read' }
1492
- : releaseCut.schemaVerdict(changes, lastFinal || 'the first commit', declared, layout);
1498
+ : releaseCut.schemaVerdict(changes, lastFinal || 'the first commit', declared, layout, none);
1493
1499
  // #441: every migration file since the last final, destructive or not — an operator-granted
1494
1500
  // automatic final refuses an ungranted one (release-finalize.js migrationGrantVerdict).
1495
1501
  const migrations = changes === null ? null : changes.filter((c) => releaseCut.isMigrationPath(c.path, declared)).map((c) => c.path);
@@ -1497,7 +1503,7 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
1497
1503
  // default-layout reading above (null = unread, never "absent"). The grant gate fails closed
1498
1504
  // without one, so its empty list never reads "nothing read" as "nothing changed".
1499
1505
  const migrationLayout = declared.length ? true : layout;
1500
- return { ci, suite, schema, switches, issues, migrations, migrationLayout };
1506
+ return { ci, suite, schema, switches, issues, migrations, migrationLayout, migrationsNone: none };
1501
1507
  }
1502
1508
 
1503
1509
  /**
@@ -1635,7 +1641,7 @@ function finalTags(repoAbs, onlyTags = null) {
1635
1641
  * since the newest final. The version is computed here only to find that tracking issue; decide()
1636
1642
  * computes it again from the same inputs, so the two cannot disagree.
1637
1643
  */
1638
- function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths, migrationLayout = null, remoteTags = null }) {
1644
+ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths, migrationLayout = null, migrationsNone = null, remoteTags = null }) {
1639
1645
  const grantDecl = policy.effective.finalGrant;
1640
1646
  const trust = trustAt(repoAbs, `${remote}/main`);
1641
1647
  const finalGrant = isGhUsable(repoAbs)
@@ -1655,7 +1661,7 @@ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, au
1655
1661
  : { ok: false, reason: 'no tracking issue yet to carry a grant' };
1656
1662
  if (grant && grant.ok) grant = { ...grant, issue: tracking.number };
1657
1663
  }
1658
- const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal, layout: migrationLayout }), paths: paths || null };
1664
+ const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal, layout: migrationLayout, none: migrationsNone }), paths: paths || null };
1659
1665
  const spacing = releaseCut.spacingVerdict({ finals: finalTags(repoAbs, remoteTags), spacingHours: policy.effective.finalSpacingHours, now: new Date().toISOString() });
1660
1666
  return { finalGrant, holds, migrations, spacing, tracking };
1661
1667
  }
@@ -1748,7 +1754,7 @@ function cmdReleaseCut(argv) {
1748
1754
  const tags = lines(git.git(['tag', '--list'], repoAbs)).filter(onRemote);
1749
1755
  const tagsAtSha = lines(git.git(['tag', '--points-at', sha], repoAbs)).filter(onRemote);
1750
1756
 
1751
- const { ci, suite, schema, switches, issues, migrations: migrationPathsSince, migrationLayout } = measureCandidateConditions(repoAbs, {
1757
+ const { ci, suite, schema, switches, issues, migrations: migrationPathsSince, migrationLayout, migrationsNone } = measureCandidateConditions(repoAbs, {
1752
1758
  sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
1753
1759
  verifying: verifyingPolicy(repoAbs), // #624: the ship gate's rule for which runs may veto
1754
1760
  });
@@ -1764,7 +1770,7 @@ function cmdReleaseCut(argv) {
1764
1770
  // #446: route deploy-tag-fast — the grant, the human veto, the migration gate and the spacing are
1765
1771
  // measured only there, so every candidate route's run is what it was.
1766
1772
  const fast = releaseCut.isFastRoute(policy) && !policy.findings.length;
1767
- const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince, migrationLayout, remoteTags }) : {};
1773
+ const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince, migrationLayout, migrationsNone, remoteTags }) : {};
1768
1774
  if (fast && auto) auto.spacing = fastFacts.spacing;
1769
1775
  // #590: route library-fast — a final with nothing deployed. The release-hold veto is its one extra
1770
1776
  // read; a hand cut also needs MIGRATION.md for a manifest-declared major (--auto reads it already).
@@ -2251,7 +2257,7 @@ function cmdReleaseFinalize(argv) {
2251
2257
  const mg = tracking && tracking.number
2252
2258
  ? migrationGrant.evaluateIssue(rec, cand.version, tracking.number, labels.MIGRATION_GRANT_LABEL, { trust })
2253
2259
  : { ok: false, reason: 'no tracking issue yet to carry a grant' };
2254
- migrations = releaseFinalize.migrationGrantVerdict({ paths: conditions.migrations, grant: mg, since: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }), layout: conditions.migrationLayout });
2260
+ migrations = releaseFinalize.migrationGrantVerdict({ paths: conditions.migrations, grant: mg, since: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }), layout: conditions.migrationLayout, none: conditions.migrationsNone });
2255
2261
  }
2256
2262
  const verdict = releaseFinalize.decide({
2257
2263
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
@@ -280,7 +280,7 @@ function detectMigrationCandidates(cfg, trackedFiles) {
280
280
  if ([...dirs].some((d) => dir.startsWith(d))) continue;
281
281
  dirs.add(dir);
282
282
  }
283
- return { declared: parsed.declared ? declared : null, candidates: [...dirs].sort() };
283
+ return { declared: parsed.declared ? declared : null, none: parsed.none, candidates: [...dirs].sort() };
284
284
  }
285
285
 
286
286
  const MIGRATION_CANDIDATES_SHOWN = 6;
@@ -288,6 +288,10 @@ const MIGRATION_CANDIDATES_SHOWN = 6;
288
288
  /** The step-2 remainder line about `migrations:` — adopt never asks it, so it always reports it. */
289
289
  function migrationsStepText(m) {
290
290
  const tail = 'project.schema.md `migrations`; `colab adopt` does not ask it, step 2';
291
+ if (m && m.none) {
292
+ const extra = m.candidates.length ? ` — but these look like migrations, check: ${listShort(m.candidates)}` : '';
293
+ return `\`migrations: none\` declared (${m.none.reason})${extra} — ${tail}`;
294
+ }
291
295
  if (m && m.declared && m.declared.length) {
292
296
  const extra = m.candidates.length ? ` — still uncovered, check: ${listShort(m.candidates)}` : '';
293
297
  return `\`migrations:\` declared (${m.declared.join(', ')})${extra} — ${tail}`;
@@ -76,30 +76,57 @@ function entryCovers(p, f) {
76
76
  * lenient in the direction that makes the gate STRICTER (it still sees
77
77
  * the path the author obviously meant); the audit fails the shape.
78
78
  *
79
+ * - a `none:` block → #672: the repo has no schema migrations, and `none:`'s value says why:
80
+ * migrations:
81
+ * none: every record lives behind another service's API
82
+ * `none` is then `{ reason }` and `paths` is []. A block, not a scalar plus a
83
+ * sibling key, because the reason is part of the declaration and must not
84
+ * drift from it (and tools/lib/yaml.js reads no flow maps). Without a reason —
85
+ * a bare `migrations: none`, an empty `none:`, a `none` list entry — it is a
86
+ * problem and `none` stays null: the grant gate keeps failing closed (#671).
87
+ * Whether a default layout contradicts it is the caller's to measure, at the
88
+ * commit (`noneContradiction`).
89
+ *
79
90
  * `paths` never includes the defaults — `isMigrationPath` always applies those itself. An entry
80
91
  * keeps its trailing `/` as written (#673): `a/b/` is a directory, `a/b` a file or a directory.
81
92
  */
82
93
  function parseMigrationPaths(doc) {
83
94
  const has = !!doc && Object.prototype.hasOwnProperty.call(doc, 'migrations');
84
95
  if (!has || doc.migrations === null || doc.migrations === undefined) {
85
- return { declared: false, paths: [], problems: [], notes: [], reason: 'migrations absent — defaults only' };
96
+ return { declared: false, paths: [], none: null, problems: [], notes: [], reason: 'migrations absent — defaults only' };
86
97
  }
87
98
  const v = doc.migrations;
88
99
  const problems = [];
89
100
  const notes = [];
101
+ const NONE_FORM = 'write it as a block naming why — `migrations:` then, indented, `none: <why this repo has no schema migrations>`';
102
+ if (v && typeof v === 'object' && !Array.isArray(v)) {
103
+ const keys = Object.keys(v);
104
+ if (keys.length !== 1 || keys[0] !== 'none') {
105
+ return { declared: true, paths: [], none: null, problems: [`migrations is a block with ${keys.map((k) => `\`${k}\``).join(', ') || 'no key'} — the only block form is \`none: <reason>\` (#672); a layout is a list (e.g. [backend/migrations/])`], notes, reason: 'migrations malformed — defaults only' };
106
+ }
107
+ const why = typeof v.none === 'string' ? v.none.trim() : '';
108
+ if (!why) return { declared: true, paths: [], none: null, problems: [`migrations: none has no reason — ${NONE_FORM}; until it has one, it declares nothing`], notes, reason: 'migrations: none without a reason — defaults only' };
109
+ return { declared: true, paths: [], none: { reason: why }, problems, notes, reason: `migrations: none — ${why}` };
110
+ }
111
+ if (typeof v === 'string' && v.trim().toLowerCase() === 'none') {
112
+ return { declared: true, paths: [], none: null, problems: [`migrations: none needs its reason — ${NONE_FORM}; until it has one, it declares nothing`], notes, reason: 'migrations: none without a reason — defaults only' };
113
+ }
90
114
  let entries;
91
115
  if (Array.isArray(v)) entries = v;
92
116
  else if (typeof v === 'string' && v.trim() !== '') {
93
117
  entries = [v];
94
118
  problems.push(`migrations is a bare string ${JSON.stringify(v)}, expected a list (e.g. [${v.trim()}])`);
95
119
  } else {
96
- return { declared: true, paths: [], problems: [`migrations is ${JSON.stringify(v)}, expected a list of repo-relative prefixes (e.g. [backend/migrations/])`], notes, reason: 'migrations malformed — defaults only' };
120
+ return { declared: true, paths: [], none: null, problems: [`migrations is ${JSON.stringify(v)}, expected a list of repo-relative prefixes (e.g. [backend/migrations/])`], notes, reason: 'migrations malformed — defaults only' };
97
121
  }
98
122
  if (Array.isArray(v) && v.length === 0) {
99
123
  notes.push('migrations is an empty list — omit the key for the defaults alone');
100
124
  }
101
125
  const paths = [];
102
126
  for (const raw of entries) {
127
+ // #672: `none` inside a list would be a path named `none` — and any declared path reads as a
128
+ // layout, so it would wave the fail-closed grant gate through. Refused, never kept as a path.
129
+ if (typeof raw === 'string' && raw.trim().toLowerCase() === 'none') { problems.push(`migrations: "none" in a list is not a path — to declare no schema migrations, ${NONE_FORM}`); continue; }
103
130
  const r = normalizeEntry(raw);
104
131
  if (r.problem) { problems.push(`migrations: ${r.problem}`); continue; }
105
132
  if (DEFAULT_MIGRATION_PATHS.includes(dirForm(r.path))) {
@@ -109,7 +136,33 @@ function parseMigrationPaths(doc) {
109
136
  if (paths.some((q) => dirForm(q) === dirForm(r.path))) { notes.push(`migrations: "${r.path}" is declared twice`); continue; }
110
137
  paths.push(r.path);
111
138
  }
112
- return { declared: true, paths, problems, notes, reason: paths.length ? `migrations: [${paths.join(', ')}] + defaults` : 'defaults only' };
139
+ return { declared: true, paths, none: null, problems, notes, reason: paths.length ? `migrations: [${paths.join(', ')}] + defaults` : 'defaults only' };
140
+ }
141
+
142
+ /**
143
+ * #672's guard: a `migrations: none` contradicted by the tree. `none` is parseMigrationPaths().none;
144
+ * `defaultDirs` the default-layout directories found at the commit (`database/migrations/`,
145
+ * `prisma/migrations/`, anywhere), or null when the tree could not be read. Returns a refusal detail,
146
+ * or null when `none` stands (or there is no `none`). An unread tree is not "absent": the caller
147
+ * fails closed on it the way it already does — this answers only "does a layout exist".
148
+ */
149
+ function noneContradiction(none, defaultDirs) {
150
+ if (!none || !defaultDirs || !defaultDirs.length) return null;
151
+ const dirs = defaultDirs.slice(0, 3).join(', ') + (defaultDirs.length > 3 ? ` (+${defaultDirs.length - 3} more)` : '');
152
+ return `the repo declares \`migrations: none\` (${none.reason}) but ${dirs} exists at the commit — a repo that can have migrations is never waved through: remove the \`none:\` block (the default layout is read without it), or remove the directory`;
153
+ }
154
+
155
+ /** The default-layout directories in a `git ls-tree -r -d --name-only` listing (#670, #672), outermost match per path. */
156
+ function defaultLayoutDirs(dirs) {
157
+ const out = [];
158
+ for (const d of dirs || []) {
159
+ if (!d) continue;
160
+ const dd = `${d}/`;
161
+ for (const def of DEFAULT_MIGRATION_PATHS) {
162
+ if ((dd === def || dd.endsWith(`/${def}`)) && !out.includes(dd)) out.push(dd);
163
+ }
164
+ }
165
+ return out;
113
166
  }
114
167
 
115
168
  /** Union of several docs' declared prefixes (trunk's + the branch's) — the gate sees every one. */
@@ -162,4 +215,5 @@ function undeclaredMigrationDirs(files, declared) {
162
215
 
163
216
  module.exports = {
164
217
  DEFAULT_MIGRATION_PATHS, parseMigrationPaths, unionPaths, isMigrationPath, isDeclaredFile, undeclaredMigrationDirs,
218
+ noneContradiction, defaultLayoutDirs,
165
219
  };
@@ -925,9 +925,14 @@ function laravelDestructive(up, addedBefore) {
925
925
  * is destructive (a destructive read file is still ✗).
926
926
  * `layout` = does `database/migrations/` or `prisma/migrations/` exist in the tree at the candidate:
927
927
  * true / false / null (the tree could not be read — never "absent"). Undefined = a caller that does
928
- * not measure it, read as today: present.
928
+ * not measure it, read as today: present. `none` (#672) = the candidate's `migrations: none` block
929
+ * (`{ reason, dirs? }`), or absent.
929
930
  */
930
- function schemaVerdict(changes, since, declared, layout) {
931
+ function schemaVerdict(changes, since, declared, layout, none) {
932
+ // #672: the candidate's `migrations: none` block. Contradicted by a default layout → refused on every
933
+ // cut, whatever changed; otherwise, with nothing changed, "not checked" naming the declaration —
934
+ // never a ✓ (nothing was read), never the "declare a layout" advice (the repo already answered).
935
+ if (none && layout === true) return { ok: false, detail: migrationPaths.noneContradiction(none, none.dirs && none.dirs.length ? none.dirs : ['a Laravel database/migrations/ or Prisma prisma/migrations/ directory']) };
931
936
  const inPaths = (changes || []).filter((c) => isMigrationPath(c.path, declared));
932
937
  // #673: a declared schema FILE (an inline schema the server applies itself) is read by the lines
933
938
  // its change added — never "unread", and an edit is never "an existing migration was rewritten".
@@ -946,9 +951,10 @@ function schemaVerdict(changes, since, declared, layout) {
946
951
  const hasDeclared = !!(declared && declared.length);
947
952
  const notChecked = (why) => ({ ok: true, checked: false, detail: `not checked — ${why}` });
948
953
  const unreadWhy = () => `${unread.length} declared migration file(s) changed since ${since} in a format this check does not read (php/sql only) — a human reads them before the final: ${unread.map((c) => c.path).join(', ')}`;
949
- const howToDeclare = 'a repo whose migrations live elsewhere declares their directory as `migrations:` in .github/project.yml (project.schema.md `migrations`); a repo with no database has nothing to declare';
954
+ const howToDeclare = 'a repo whose migrations live elsewhere declares their directory as `migrations:` in .github/project.yml (project.schema.md `migrations`); a repo with no schema migrations declares `migrations:` then `none: <why>` (#672)';
950
955
  if (!migrations.length && !schemaFiles.length) {
951
956
  if (unread.length) return notChecked(unreadWhy());
957
+ if (none && layout === false) return notChecked(`the repo declares \`migrations: none\` (${none.reason}) and no Laravel or Prisma migrations directory exists at the candidate, so there is no schema to read`);
952
958
  if (!hasDeclared && layout === false) return notChecked(`no Laravel database/migrations/ or Prisma prisma/migrations/ directory at the candidate and no \`migrations:\` declared, so no migration was read — ${howToDeclare}`);
953
959
  if (!hasDeclared && layout === null) return notChecked(`the tree at the candidate could not be read for a migration layout, so no migration was read — ${howToDeclare}`);
954
960
  return { ok: true, detail: `no migration file changed since ${since} (${scope})` };
@@ -61,6 +61,7 @@
61
61
  */
62
62
 
63
63
  const releaseTag = require('./release-tag');
64
+ const migrationPaths = require('./migration-paths');
64
65
 
65
66
  // The tracking marker and the event marker are wire format: codec/release.js (#498, epic #496),
66
67
  // re-exported below under the names this module always had. VERSION_RE is the codec's, so a
@@ -564,17 +565,25 @@ function regressionVerdict(edges, { periodStart }) {
564
565
  * true = a `migrations:` prefix is declared or a default layout (Laravel database/migrations/,
565
566
  * Prisma prisma/migrations/) exists in the tree; false = neither, so an empty `paths` is "nothing
566
567
  * read", not "nothing changed"; null/absent = the tree could not be read. An empty `paths` passes
567
- * only with a layout. Returns { ok, detail } (+ unread: true when something could not be read).
568
+ * only with a layout — or (#672) with `none`: the candidate's committed `migrations: none` block
569
+ * (`{ reason, dirs? }` — `dirs` the default-layout directories found, for the refusal), honoured only where no default layout exists (`layout` false). With a layout there
570
+ * (`layout` true) the declaration is a contradiction and the gate refuses, migrations changed or not:
571
+ * a repo that can have migrations is never waved through; an unread tree still fails closed.
572
+ * Returns { ok, detail } (+ unread: true when something could not be read).
568
573
  */
569
- function migrationGrantVerdict({ paths, grant, since, layout }) {
574
+ function migrationGrantVerdict({ paths, grant, since, layout, none }) {
570
575
  if (paths === null || paths === undefined) return { ok: false, unread: true, detail: 'the migration files since the last final could not be read — an unread migration is not an absent one' };
576
+ if (none) {
577
+ if (layout === true) return { ok: false, detail: `${migrationPaths.noneContradiction(none, none.dirs && none.dirs.length ? none.dirs : ['a Laravel database/migrations/ or Prisma prisma/migrations/ directory'])} — then the usual migration grant applies (COLAB_HUMAN=1 colab migration-grant <tracking issue> --branch <version>)` };
578
+ if (layout === false && !paths.length) return { ok: true, detail: `no schema migrations to read since ${since || 'the first commit'}: the repo declares \`migrations: none\` (${none.reason}), and no Laravel or Prisma migrations directory exists at the candidate` };
579
+ }
571
580
  if (!paths.length) {
572
581
  // #671: fail closed where nothing could have been seen — an automatically deployed final never
573
582
  // reads "nothing read" as "nothing changed". The way out is named in the detail, never implied —
574
583
  // route-neutral: release finalize prints its own human command, and route deploy-tag-fast has none.
575
584
  // #673: a schema applied inline by the server's own code is declarable too — as the FILE — and the
576
585
  // detail names the grant command that clears its next change, so no one reaches for a raw tag.
577
- const wayOut = 'declare where the schema lives as `migrations:` in .github/project.yml (project.schema.md `migrations`) — a migration directory (`migrations: [backend/migrations/]`) or, for a schema the server applies inline, the file itself (`migrations: [server/db.ts]`); a change under it then clears the usual way (COLAB_HUMAN=1 colab migration-grant <tracking issue> --branch <version>). Until then the final is a human act, not the grant\'s — and a repo with no database has no layout to declare, so its final stays one';
586
+ const wayOut = 'declare where the schema lives as `migrations:` in .github/project.yml (project.schema.md `migrations`) — a migration directory (`migrations: [backend/migrations/]`) or, for a schema the server applies inline, the file itself (`migrations: [server/db.ts]`); a change under it then clears the usual way (COLAB_HUMAN=1 colab migration-grant <tracking issue> --branch <version>). A repo with no schema migrations at all declares that instead, with its reason (`migrations:` then `none: <why>`, #672). Until then the final is a human act, not the grant\'s';
578
587
  if (layout === false) return { ok: false, detail: `no migration was read since ${since || 'the first commit'}: no \`migrations:\` declared and no Laravel database/migrations/ or Prisma prisma/migrations/ directory at the candidate, so a migration elsewhere would be invisible — ${wayOut}` };
579
588
  if (layout !== true) return { ok: false, unread: true, detail: `the tree at the candidate could not be read for a migration layout, so an empty migration list since ${since || 'the first commit'} is not evidence that none changed — ${wayOut}` };
580
589
  return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };