@futurelastic/colab-handbook 1.12.0-rc.50 → 1.12.0-rc.52

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.50"
30
+ "version": "1.12.0-rc.52"
31
31
  }
package/tools/colab CHANGED
@@ -1258,8 +1258,8 @@ Refuses, naming each failed condition (all are reported, not just the first):
1258
1258
  switch-dependencies a colab:switch marker is malformed, or a finished switch needs one that is not
1259
1259
  manifest-version the tag does not equal the version a manifest declares (VERSION, package.json,
1260
1260
  Cargo.toml [package], pyproject.toml [project]/[tool.poetry]) — none declared
1261
- passes: the tag is the version (#424). With release.version-source: tag (#438)
1262
- 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
1263
1263
  stamped from the tag by the repo's own release step (never on trunk)
1264
1264
  on-trunk the commit is not an ancestor of main, or the checkout is shallow (#424)
1265
1265
  outranks-final the version is not strictly greater than the highest final tag (#424)
@@ -1850,8 +1850,8 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1850
1850
 
1851
1851
  manifest-version on-trunk outranks-final — #424's pre-tag checks, required before any final:
1852
1852
  the final equals every declared manifest version, its commit is on main (a shallow
1853
- checkout refuses), and it outranks the highest final tag. With release.version-source:
1854
- 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
1855
1855
 
1856
1856
  final-grant migration-grant — #441, only where release.final-grant lets a deploy-tag final be
1857
1857
  automatic: the decision issue it names must still carry a recorded, trusted, not
@@ -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