@futurelastic/colab-handbook 1.12.0-rc.49 → 1.12.0-rc.51

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
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.49"
30
+ "version": "1.12.0-rc.51"
31
31
  }
package/tools/colab CHANGED
@@ -129,7 +129,8 @@ function resolveRepo(opts) {
129
129
  * `.github/project.yml` into the main checkout when run from inside a worktree it was supposed
130
130
  * to target — silently violating "the main checkout stays on trunk at rest" (#258). This
131
131
  * mirrors the `opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null)` pattern
132
- * already used at most other cmd* call sites, as a named, reusable resolver.
132
+ * once used at most other cmd* call sites (normalised since #487 — resolveRepoOrCwd), as a named,
133
+ * reusable resolver for the one question that genuinely wants the caller's own tree.
133
134
  */
134
135
  function resolveWorkingRepo(opts) {
135
136
  let r = opts.repo;
@@ -154,16 +155,60 @@ function knownRepos(config) {
154
155
  return extra;
155
156
  }
156
157
 
157
- /** Find a single claim by issue number, optionally constrained to a repo. */
158
+ /**
159
+ * The repo a lookup with no --repo is about: --repo (normalised) or the MAIN root of cwd, or null.
160
+ *
161
+ * #487: this used to be spelled `resolveRepoOrCwd(opts)`
162
+ * at a dozen call sites — normalised with --repo, NOT normalised without it. Run from inside a
163
+ * linked worktree, the bare form answered with the worktree's own root, so a release looked up
164
+ * `<worktree>#N` while the claim sat under `<mainRoot>#N`. Every one of those sites is about repo
165
+ * STATE or the tracker (claims, ports, grants, events), never a committable file — for that,
166
+ * resolveWorkingRepo() is the deliberate exception.
167
+ */
168
+ function resolveRepoOrCwd(opts) {
169
+ return opts.repo ? resolveRepo(opts) : (git.mainRepoRoot(process.cwd()) || null);
170
+ }
171
+
172
+ /**
173
+ * The main checkout a claim row belongs to, given the path in its key (or its `repo` field).
174
+ *
175
+ * #487: an older writer (`claims --sync` run from inside a linked worktree) keyed rows by the
176
+ * WORKTREE's path. Those rows outlive the worktree, and the path no longer exists, so nothing could
177
+ * resolve it back to its repo — `release` missed them with and without --repo, forever. A path that
178
+ * exists resolves through git; a vanished one is attributed to the nearest existing ancestor's main
179
+ * root, but only when that ancestor IS a repo the path sits inside — never a guess across repos.
180
+ */
181
+ function claimHomeRoot(p) {
182
+ if (!p) return p;
183
+ if (fs.existsSync(p)) return git.mainRepoRoot(p) || p;
184
+ let dir = path.dirname(p);
185
+ while (dir && dir !== path.dirname(dir) && !fs.existsSync(dir)) dir = path.dirname(dir);
186
+ const root = dir && fs.existsSync(dir) ? git.mainRepoRoot(dir) : null;
187
+ return root && p.startsWith(`${root}${path.sep}`) ? root : p;
188
+ }
189
+
190
+ /** Does the claim key `k` belong to `repoAbs` (a main root)? Includes legacy worktree-keyed rows (#487). */
191
+ function claimKeyInRepo(k, repoAbs) {
192
+ if (k.startsWith(`${repoAbs}#`)) return true;
193
+ const keyPath = k.slice(0, k.lastIndexOf('#'));
194
+ return keyPath.startsWith(`${repoAbs}${path.sep}`) && claimHomeRoot(keyPath) === repoAbs;
195
+ }
196
+
197
+ /**
198
+ * Find a single claim by issue number, optionally constrained to a repo. `repo` in the result is
199
+ * the claim's MAIN root — for a legacy worktree-keyed row (#487) that is not `claim.repo`, which
200
+ * names a directory that may no longer exist; anything talking to the tracker must use `repo`.
201
+ */
158
202
  function findClaim(st, num, repoAbs) {
159
203
  const matches = Object.entries(st.claims).filter(([, c]) => normIssueNum(c.issue) === num);
160
- const scoped = repoAbs ? matches.filter(([k]) => k.startsWith(`${repoAbs}#`)) : matches;
204
+ const scoped = repoAbs ? matches.filter(([k]) => claimKeyInRepo(k, repoAbs)) : matches;
161
205
  if (scoped.length === 0) return null;
162
206
  if (scoped.length > 1) {
163
- const repos = scoped.map(([k]) => shortRepo(k.split('#')[0])).join(', ');
207
+ const repos = scoped.map(([k]) => shortRepo(k.slice(0, k.lastIndexOf('#')))).join(', ');
164
208
  throw new UserError(`Issue #${num} is claimed in multiple repos (${repos}) — disambiguate with --repo`);
165
209
  }
166
- return { key: scoped[0][0], claim: scoped[0][1] };
210
+ const [key, claim] = scoped[0];
211
+ return { key, claim, repo: repoAbs || claimHomeRoot(claim.repo || key.slice(0, key.lastIndexOf('#'))) };
167
212
  }
168
213
 
169
214
  function isGhUsable(repoAbs) {
@@ -1213,8 +1258,8 @@ Refuses, naming each failed condition (all are reported, not just the first):
1213
1258
  switch-dependencies a colab:switch marker is malformed, or a finished switch needs one that is not
1214
1259
  manifest-version the tag does not equal the version a manifest declares (VERSION, package.json,
1215
1260
  Cargo.toml [package], pyproject.toml [project]/[tool.poetry]) — none declared
1216
- passes: the tag is the version (#424). With release.version-source: tag (#438)
1217
- a differing manifest is DERIVABLE — skipped, named in the tag message, and
1261
+ passes: the tag is the version (#424). Under release.version-source: tag (#438;
1262
+ the default where the machine cuts the tag, #484) a differing manifest is DERIVABLE — skipped, named in the tag message, and
1218
1263
  stamped from the tag by the repo's own release step (never on trunk)
1219
1264
  on-trunk the commit is not an ancestor of main, or the checkout is shallow (#424)
1220
1265
  outranks-final the version is not strictly greater than the highest final tag (#424)
@@ -1805,8 +1850,8 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1805
1850
 
1806
1851
  manifest-version on-trunk outranks-final — #424's pre-tag checks, required before any final:
1807
1852
  the final equals every declared manifest version, its commit is on main (a shallow
1808
- checkout refuses), and it outranks the highest final tag. With release.version-source:
1809
- tag (#438) a manifest that differs is skipped as derivable and named, not refused
1853
+ checkout refuses), and it outranks the highest final tag. Under release.version-source:
1854
+ tag (#438; the default where the machine cuts the tag, #484) a manifest that differs is skipped as derivable and named, not refused
1810
1855
 
1811
1856
  final-grant migration-grant — #441, only where release.final-grant lets a deploy-tag final be
1812
1857
  automatic: the decision issue it names must still carry a recorded, trusted, not
@@ -2183,7 +2228,7 @@ function cmdRelease(argv) {
2183
2228
  });
2184
2229
  if (opts.help || opts._.length === 0) return print(HELP_RELEASE);
2185
2230
  const num = normIssueNum(opts._[0]);
2186
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
2231
+ const repoAbs = resolveRepoOrCwd(opts);
2187
2232
 
2188
2233
  // #164: look the claim up WITHOUT deleting it yet — the gh write below can fail (GraphQL AND
2189
2234
  // REST both rate-limited, network down, ...), and deleting first would clear the one local
@@ -2209,7 +2254,7 @@ function cmdRelease(argv) {
2209
2254
  * Returns { ghFailed, worktree, remaining }.
2210
2255
  */
2211
2256
  function releaseFoundClaim(num, found, opts = {}) {
2212
- const repo = found.claim.repo;
2257
+ const repo = found.repo || found.claim.repo; // #487: the MAIN root, even for a legacy worktree-keyed row
2213
2258
  const wtName = found.claim.worktree;
2214
2259
 
2215
2260
  let ghFailed = false;
@@ -2332,7 +2377,7 @@ function cmdIssueFiled(argv) {
2332
2377
  });
2333
2378
  if (opts.help || opts._.length === 0) return print(HELP_ISSUE_FILED);
2334
2379
  const num = normIssueNum(opts._[0]);
2335
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
2380
+ const repoAbs = resolveRepoOrCwd(opts);
2336
2381
  if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
2337
2382
 
2338
2383
  pushEvent('issue-filed', { repo: repoAbs, issue: num });
@@ -2504,7 +2549,7 @@ function cmdGateRecorded(argv) {
2504
2549
  });
2505
2550
  if (opts.help) return print(HELP_GATE_RECORDED);
2506
2551
 
2507
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.mainRepoRoot(process.cwd()) || null);
2552
+ const repoAbs = resolveRepoOrCwd(opts);
2508
2553
  if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
2509
2554
 
2510
2555
  let wtName = opts.worktree || null;
@@ -3278,7 +3323,7 @@ function cmdReadiness(argv) {
3278
3323
  });
3279
3324
  if (opts.help || opts._.length === 0) return print(HELP_READINESS);
3280
3325
  const num = normIssueNum(opts._[0]);
3281
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
3326
+ const repoAbs = resolveRepoOrCwd(opts);
3282
3327
  if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
3283
3328
 
3284
3329
  // No local fallback, on purpose. A claim can degrade to local-only because it also has a fast
@@ -3478,7 +3523,7 @@ function cmdBlocked(argv) {
3478
3523
  });
3479
3524
  if (argErr) throw new UserError(argErr);
3480
3525
 
3481
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
3526
+ const repoAbs = resolveRepoOrCwd(opts);
3482
3527
  if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
3483
3528
 
3484
3529
  if (!isGhUsable(repoAbs)) {
@@ -3739,7 +3784,7 @@ function cmdMigrationGrant(argv) {
3739
3784
  return 1;
3740
3785
  }
3741
3786
 
3742
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
3787
+ const repoAbs = resolveRepoOrCwd(opts);
3743
3788
  if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
3744
3789
 
3745
3790
  // Argument validation and local ref resolution run BEFORE isGhUsable, deliberately — they are
@@ -3945,7 +3990,7 @@ function cmdMigrationGrantRevoke(repoAbs, num) {
3945
3990
  }
3946
3991
 
3947
3992
  function cmdMigrationGrantList(opts) {
3948
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
3993
+ const repoAbs = resolveRepoOrCwd(opts);
3949
3994
  if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
3950
3995
  if (!isGhUsable(repoAbs)) {
3951
3996
  throw new UserError(`gh not usable here (${ghUnusableWhy(repoAbs)}) — cannot list migration grants`);
@@ -4080,7 +4125,7 @@ function cmdDecision(argv) {
4080
4125
  throw new UserError('--ruled-by <name> is required — names the human whose call this is, never the typist (CONVENTIONS.md §5, Provenance)');
4081
4126
  }
4082
4127
 
4083
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
4128
+ const repoAbs = resolveRepoOrCwd(opts);
4084
4129
  if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
4085
4130
 
4086
4131
  if (!isGhUsable(repoAbs)) {
@@ -4226,7 +4271,7 @@ function cmdDecisionReopen(repoAbs, num, opts, body) {
4226
4271
  }
4227
4272
 
4228
4273
  function cmdDecisionList(opts) {
4229
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
4274
+ const repoAbs = resolveRepoOrCwd(opts);
4230
4275
  if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
4231
4276
  if (!isGhUsable(repoAbs)) {
4232
4277
  throw new UserError(`gh not usable here (${ghUnusableWhy(repoAbs)}) — cannot list decisions`);
@@ -4450,7 +4495,7 @@ function cmdCiGrant(argv) {
4450
4495
  return 1;
4451
4496
  }
4452
4497
 
4453
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
4498
+ const repoAbs = resolveRepoOrCwd(opts);
4454
4499
  if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
4455
4500
 
4456
4501
  // Argument validation and local ref resolution BEFORE isGhUsable — same reasoning as
@@ -4576,7 +4621,7 @@ function cmdCiGrantRevoke(repoAbs, num) {
4576
4621
  }
4577
4622
 
4578
4623
  function cmdCiGrantList(opts) {
4579
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
4624
+ const repoAbs = resolveRepoOrCwd(opts);
4580
4625
  if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
4581
4626
  if (!isGhUsable(repoAbs)) {
4582
4627
  throw new UserError(`gh not usable here (${ghUnusableWhy(repoAbs)}) — cannot list CI grants`);
@@ -4683,8 +4728,11 @@ function syncClaims({ prune = false } = {}) {
4683
4728
  if (!git.ghAvailable()) { warn('gh not available — --sync skipped'); return; }
4684
4729
  const st = state.loadState();
4685
4730
  // repos represented locally + repos with a resolvable remote (#301: not necessarily `origin`)
4686
- const repos = new Set(Object.values(st.claims).map((c) => c.repo));
4687
- const cur = git.repoRoot(process.cwd());
4731
+ // #487: every repo here is a MAIN root. This was the writer of the worktree-keyed rows nothing could
4732
+ // release: from inside a linked worktree, repoRoot(cwd) is the worktree, so every assigned issue
4733
+ // was re-added as `<worktree>#N` — a second row beside the real `<mainRoot>#N`, outliving the dir.
4734
+ const repos = new Set(Object.values(st.claims).map((c) => claimHomeRoot(c.repo)).filter(Boolean));
4735
+ const cur = git.mainRepoRoot(process.cwd());
4688
4736
  if (cur) repos.add(cur);
4689
4737
 
4690
4738
  const added = [], removed = [];
@@ -4711,7 +4759,7 @@ function syncClaims({ prune = false } = {}) {
4711
4759
  }
4712
4760
  // local → GH: REMOVE stale local claims ONLY when --prune is given
4713
4761
  if (prune) {
4714
- const localForRepo = Object.entries(st.claims).filter(([k]) => k.startsWith(`${repoAbs}#`));
4762
+ const localForRepo = Object.entries(st.claims).filter(([k]) => claimKeyInRepo(k, repoAbs));
4715
4763
  for (const [key, c] of localForRepo) {
4716
4764
  const num = normIssueNum(c.issue);
4717
4765
  if (!assignedSet.has(num)) {
@@ -4844,7 +4892,7 @@ function cmdPortAlloc(argv) {
4844
4892
  const config = state.loadConfig();
4845
4893
  const count = opts.count ? parseInt(opts.count, 10) : 1;
4846
4894
  if (!Number.isInteger(count) || count < 1) throw new UserError('--count must be a positive integer');
4847
- const explicitRepo = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
4895
+ const explicitRepo = resolveRepoOrCwd(opts);
4848
4896
  const atPorts = parseAtPorts(opts);
4849
4897
 
4850
4898
  // For range resolution, a --worktree owner's repo wins over cwd (its project.yml window applies).
@@ -4891,7 +4939,7 @@ function cmdPortFree(argv) {
4891
4939
  flags: { '-h': 'help', '--help': 'help' },
4892
4940
  });
4893
4941
  if (opts.help) return print(HELP_PORT);
4894
- const repoAbs = opts.repo ? resolveRepo(opts) : (git.repoRoot(process.cwd()) || null);
4942
+ const repoAbs = resolveRepoOrCwd(opts);
4895
4943
 
4896
4944
  const freed = state.mutate((st) => {
4897
4945
  let targets = [];
@@ -944,6 +944,7 @@ function decide(facts) {
944
944
  bump: v.ok ? v.bump : (v.bump || null), overridden: v.ok ? v.overridden : null,
945
945
  signals: f.auto ? f.auto.signals || null : null, migration: v.migration || null,
946
946
  derivable,
947
+ versionSourceDeclared: !!(p && p.effective && p.effective.versionSourceDeclared),
947
948
  final: fast, grant, handoff,
948
949
  healthGate: fast ? p.effective.healthGate : null,
949
950
  };
@@ -970,7 +971,11 @@ function tagMessage(verdict, { sha, lastFinal }) {
970
971
  ...(verdict.migration && verdict.migration.section ? ['Migration:', '', verdict.migration.section, ''] : []),
971
972
  ...(fast && verdict.grant ? [`Automatic final granted by: release.final-grant -> decision #${verdict.grant.issue}${verdict.grant.ruledBy ? `, ruled by ${verdict.grant.ruledBy}` : ''} (an operator's per-repo grant; deleting it, or route: deploy-tag, revokes it)`] : []),
972
973
  ...(fast && verdict.healthGate ? [`Health gate: ${verdict.healthGate.url} (rollback: ${verdict.healthGate.rollback}) — the release workflow deploys this tag in the same run and verifies it there`, ''] : []),
973
- ...(verdict.derivable && verdict.derivable.length ? [`Derivable manifests (release.version-source: tag, not checked against the tag): ${verdict.derivable.join(', ')}`, ''] : []),
974
+ // #484: a defaulted `tag` says so — the stale manifest is named on every cut, so an artifact that
975
+ // reads it unstamped is visible here rather than discovered by a user.
976
+ ...(verdict.derivable && verdict.derivable.length ? [verdict.versionSourceDeclared
977
+ ? `Derivable manifests (release.version-source: tag, not checked against the tag): ${verdict.derivable.join(', ')}`
978
+ : `Derivable manifests (release.version-source: tag — the default on a route that tags automatically, #484; not checked against the tag): ${verdict.derivable.join(', ')}`, ''] : []),
974
979
  'Conditions (CONVENTIONS.md §6):',
975
980
  ...verdict.checks.map((c) => `- ${c.condition}: ${c.detail}`),
976
981
  '',
@@ -18,7 +18,7 @@
18
18
  * exports: <path> # #422 — a committed list of public symbols, one per line
19
19
  * npm: <dir> # #433 — publish this package directory to npm from release-auto.yml
20
20
  * npm-gate: <command> # #433 — the pack-allowlist gate, run before every npm publish
21
- * version-source: tag # #438 — tag | manifest: is a manifest's version checked, or derivable?
21
+ * version-source: tag # #438 — tag | manifest: is a manifest's version checked, or derivable? (#484: default per route)
22
22
  * final-grant: 123 # #441 — an operator's recorded decision letting deploy-tag's final be automatic
23
23
  * health-url: https://… # #446/#452 — deploy-tag or deploy-tag-fast (required there): the public endpoint reporting the running version
24
24
  * rollback: auto # #446 — deploy-tag-fast only: the deploy rolls itself back when that check fails
@@ -48,12 +48,14 @@
48
48
  const axisAuthority = require('./axis-authority.js');
49
49
 
50
50
  const KEYS = Object.freeze(['route', 'candidates', 'candidates-per-day', 'test-period', 'final', 'guard-run', 'guard-result', 'exports', 'npm', 'npm-gate', 'version-source', 'final-grant', 'health-url', 'rollback', 'final-spacing']);
51
- // #438: where the version a tag names comes from. `manifest` (the default) — every declared manifest
52
- // (VERSION, package.json, Cargo.toml, pyproject.toml) must already equal the tag, so a human bumps it
53
- // on trunk first. `tag` — the tag is the version and the manifests are DERIVABLE: the pre-tag check
54
- // skips them, and the repo's own release/deploy step stamps the number from the tag (on a deploy-only
55
- // ref or at build time — never a commit on trunk). Neither widens nor narrows a route: it decides
56
- // which file is the source of a number, never whether a tag is cut.
51
+ // #438: where the version a tag names comes from. `manifest` — every declared manifest (VERSION,
52
+ // package.json, Cargo.toml, pyproject.toml) must already equal the tag, so a human bumps it on trunk
53
+ // first. `tag` — the tag is the version and the manifests are DERIVABLE: the pre-tag check skips
54
+ // them, and the repo's own release/deploy step stamps the number from the tag (on a deploy-only ref
55
+ // or at build time — never a commit on trunk). Neither widens nor narrows a route: it decides which
56
+ // file is the source of a number, never whether a tag is cut.
57
+ // #484: the DEFAULT is per route (defaultVersionSource below) — `tag` wherever the machine cuts the
58
+ // tag, `manifest` wherever a person does. A declared value always wins, in either direction.
57
59
  const VERSION_SOURCES = Object.freeze(['manifest', 'tag']);
58
60
  // #441: the one route whose final may become automatic by an operator's grant, and the row it must
59
61
  // sit on — `deploy: tag` only. `deploy: manual` stays human: a person runs that deploy anyway.
@@ -171,10 +173,23 @@ function deriveDefault(cfg) {
171
173
  };
172
174
  }
173
175
 
176
+ /**
177
+ * #484: the version-source a policy defaults to when `release.version-source` is not declared.
178
+ * `tag` wherever the machine cuts the tag — automatic candidates (rapid-app, public-tool,
179
+ * deploy-tag) or a final tagged by `release cut --auto` itself (deploy-tag-fast's on-green-head):
180
+ * the release workflow never pushes to trunk, so nobody is there to bump a manifest before each
181
+ * cut, and a `manifest` default refuses the first candidate after a final and every one after it.
182
+ * `manifest` everywhere a person cuts the tag (and can bump the file first). Read from the
183
+ * EFFECTIVE policy, so a `candidates: off` narrowing moves the default back to `manifest`.
184
+ */
185
+ function defaultVersionSource(p) {
186
+ return p && (p.candidates === 'auto' || p.finalize === 'on-green-head') ? 'tag' : 'manifest';
187
+ }
188
+
174
189
  /** A route's policy as an effective-shaped object (no `why`). */
175
190
  function routePolicy(route) {
176
191
  const p = ROUTE_POLICY[route];
177
- return p ? { route, candidates: p.candidates, candidatesPerDay: p.candidatesPerDay, testPeriodDays: p.testPeriodDays, final: p.final, finalize: p.finalize, npm: null, versionSource: 'manifest', finalGrant: null, healthGate: null, healthUrl: null, finalSpacingHours: null } : null;
192
+ return p ? { route, candidates: p.candidates, candidatesPerDay: p.candidatesPerDay, testPeriodDays: p.testPeriodDays, final: p.final, finalize: p.finalize, npm: null, versionSource: defaultVersionSource(p), versionSourceDeclared: false, finalGrant: null, healthGate: null, healthUrl: null, finalSpacingHours: null } : null;
178
193
  }
179
194
 
180
195
  /** `6h` -> 6, `2d` -> 48; anything else (including `30m`, `0h`) -> null. */
@@ -227,7 +242,8 @@ function evaluateRelease(cfg) {
227
242
  const fromDerived = () => ({
228
243
  route: derived.route, candidates: derived.candidates, candidatesPerDay: derived.candidatesPerDay,
229
244
  testPeriodDays: derived.testPeriodDays, final: derived.final, finalize: derived.finalize, npm: null,
230
- versionSource: 'manifest', finalGrant: null, healthGate: null, healthUrl: null, finalSpacingHours: null,
245
+ versionSource: defaultVersionSource(derived), versionSourceDeclared: false,
246
+ finalGrant: null, healthGate: null, healthUrl: null, finalSpacingHours: null,
231
247
  });
232
248
  let effective = fromDerived();
233
249
  const findings = [];
@@ -358,11 +374,14 @@ function evaluateRelease(cfg) {
358
374
  } else effective.testPeriodDays = days;
359
375
  }
360
376
 
361
- // #438: where the tag's version comes from.
377
+ // #438: where the tag's version comes from. #484: the default follows the route as narrowed so
378
+ // far (a `candidates: off` narrowing hands the cut back to a person, and with it `manifest`);
379
+ // a valid declared value wins either way, an invalid one is a finding and leaves the default.
380
+ effective.versionSource = defaultVersionSource(effective);
362
381
  if ('version-source' in raw) {
363
382
  const v = raw['version-source'];
364
383
  if (!VERSION_SOURCES.includes(v)) fail(`release.version-source is ${JSON.stringify(v)}, expected "tag" or "manifest"`);
365
- else effective.versionSource = v;
384
+ else { effective.versionSource = v; effective.versionSourceDeclared = true; }
366
385
  }
367
386
 
368
387
  // #446: the fast route's own keys — only there, and the floor on spacing. #452: `health-url` is
@@ -443,5 +462,5 @@ module.exports = {
443
462
  VERSION_SOURCES, GRANTABLE_ROUTE, GRANTABLE_ROW, GRANTABLE_ROUTES, FAST_ROUTE, FAST_KEYS, FAST_ONLY_KEYS, HEALTH_URL_ROUTES, ROLLBACK, FINAL_SPACING_HOURS,
444
463
  parseGrantIssue, finalGrantVerdict, parseSpacing, validHealthUrl, fastRoutePrerequisites,
445
464
  KEYS, INPUT_KEYS, NPM_KEYS, NPM_ROUTES, CANDIDATES, FINAL, TEST_PERIOD_DAYS, ROUTES, ROUTE_POLICY, ROW_ROUTES,
446
- deriveDefault, evaluateRelease, parseTestPeriod, routePolicy,
465
+ deriveDefault, evaluateRelease, parseTestPeriod, routePolicy, defaultVersionSource,
447
466
  };
@@ -156,7 +156,9 @@ function manifestVersions(readFile) {
156
156
  * checkout cannot answer (null = not measured)
157
157
  * tags every tag name in the repo — the finals among them are what the version must outrank
158
158
  * trunk the trunk name, for the detail text
159
- * versionSource #438 — 'manifest' (default): every declared manifest must equal the tag. 'tag'
159
+ * versionSource #438 — 'manifest' (this function's default; the policy's own default is per
160
+ * route since #484 — release-policy.js defaultVersionSource): every declared manifest
161
+ * must equal the tag. 'tag'
160
162
  * (`release.version-source: tag`): the manifests are DERIVABLE — the repo's own
161
163
  * release/deploy step stamps them from the tag, never on trunk — so a manifest that
162
164
  * differs is skipped and named, not refused. A manifest that cannot be read at all