@bongos/core 1.19.806 → 1.19.807

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.806",
-  "core_contract": "1.19.806",
-  "source_commit": "f8c520693845c7f9adf348df09423e304f95209a",
+  "core_version": "1.19.807",
+  "core_contract": "1.19.807",
+  "source_commit": "6154a1dcba2e8a7f84903bbf6a300e969382af47",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T04:40:33.822Z",
+  "built_at": "2026-09-17T04:54:31.340Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 487,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2708,
-  "tree_sha256": "9bbb51184882b2c5393431e5c4ef4cd40107a22ea904758de3f6fa51f794e9b2",
+  "tree_sha256": "4d685c0339573af46854e0aac2b8a2b3981f2a289478dadf3d99f83b066b9cdc",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2532,7 +2532,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "42401492ce439f5d5e9bd8acbb2dd594be86a2a85490c7be364639c74975ff6b"
+      "sha256": "bf7add64727463c6823ec5b4eb2031ba38eca1adbcacbc29cfa0c22799459865"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2792,7 +2792,7 @@
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
-      "sha256": "041955ed109343181ea563e47e905c59e3bbd052e4dc3988b5ea34fbe5029f16"
+      "sha256": "ffe0add6718e0620144e8b786f237153aca9888a9f9052adb41948fcbc17ddec"
     },
     {
       "path": "docs/recipes/windows-builders.md",
@@ -7722,12 +7722,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "8d7000897d233110534c4beb2ecd9e8d2688239abadf5b7a37f48f8a90c7fcad"
+      "sha256": "784deb39aa5635d1c72a322fc760668827b10bd9be69a6350c3cdfae04d48ed5"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "a9a60765fc2fd7cd71a31ba524f0be16d9c7ca77282c1baa2dfd6b88ac6bdc06"
+      "sha256": "9c405eb98a8f839686c4b573afd3c9af4efda58095e2b6a6bd6fd9c335f919b4"
     },
     {
       "path": "public-docs/index.html",
@@ -8742,7 +8742,7 @@
     {
       "path": "scripts/gds/routine-schedule.js",
       "mode": "0000644",
-      "sha256": "0d75c6b9be5a67738c91e55cda9084e10d7c64aa49c80ce9c0fa4219afcbd14c"
+      "sha256": "9ef89c7bc7e2784abcbaecbdddbb03fe089019597a68323faa45bd1c887f199f"
     },
     {
       "path": "scripts/gds/run-routine.js",
@@ -9617,7 +9617,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a7b864edf20ff522c36758ae16b9050cdc2621595cd6883ae9484547126155d1"
+      "sha256": "305f25717a1dbfdf109ba439f0160a047b374a80d20ce0111aad0f2a8e70ccde"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12697,7 +12697,7 @@
     {
       "path": "tests/routine_schedule.mjs",
       "mode": "0000644",
-      "sha256": "ba7f5690b9a3649a4c4cd2571d316aa837ffc01874d57aaa418dc72683c6a1f1"
+      "sha256": "ba6bc3abb46cdaf2100efb843d25526212d747feb71f51b13214ef3ffc92d624"
     },
     {
       "path": "tests/routine_timers.mjs",

package/docs/module-api-changelog.md

@@ -2086,5 +2086,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.804 with no explicit bump. run 35180781365. (task 1002620)
   1.19.806 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.805 with no explicit bump. run 35182765995. (task 1002620)
+  1.19.807 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.806 with no explicit bump. run 35183654397. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/upgrading-the-core.md

@@ -114,6 +114,45 @@ Each subscribed instance: read its installed core → ask the registry (`npm vie
 
 **Triple-gated, so nothing moves by accident:** the `core-update-subscription` routine is `requiresAutonomy: true` + **default OFF** in [`config/scheduled-routines.json`](../../config/scheduled-routines.json), the roster ships empty, and every upgrade is health-gated. Arm it by enabling the routine's timer on the control plane once autonomy is on.
 
+#### How often it sweeps — the lag knob (task 1003674)
+
+**This timer's period IS the delay between a builder's merge and the live site
+serving it.** Everything upstream is already fast: CI publishes to npm within
+~2 minutes of a merge. The pull-deploy timer is fast too, but it watches the
+*instance repo*, not npm — it logs `already at origin/main — nothing to deploy`
+and only acts once a pin-bump commit exists. **This sweep is what creates that
+commit**, so nothing reaches the site between its runs. Left at `OnCalendar=daily`
+the worst case is ~24 hours, which is what made shipped work look unshipped and
+pushed the owner into manual go-lives.
+
+Install it at the declared cadence (`15min` in `config/scheduled-routines.json`):
+
+```ini
+# /etc/systemd/system/<instance>-core-update-subscription.timer
+[Timer]
+OnCalendar=*:0/15
+RandomizedDelaySec=120
+Persistent=true
+```
+
+```bash
+sudo systemctl daemon-reload && sudo systemctl restart <instance>-core-update-subscription.timer
+systemctl list-timers '*core-update-subscription*' --no-pager   # confirm the next elapse is minutes away
+```
+
+**Do not go below ~5 minutes.** An upgrading run takes ~2 minutes; at a tighter
+spacing runs overlap. A run with nothing to take costs one `npm view` and exits,
+so 15 minutes is cheap — the cost scales with releases, not with checks.
+
+This does **not** weaken the pinned-core model ([ADR 0108](../adr/0108-instance-composition-configurable-root.md)):
+the pin still exists, a bad release can still be frozen or rolled back, and every
+upgrade stays health-gated with auto-rollback (task 2149). A faster sweep only
+removes the wait.
+
+**Verify:** merge something, wait for the next elapse, and confirm
+`curl -s https://<instance>/version` reports the new `coreVersion` with nobody
+running a go-live.
+
 **Not covered:** multi-host / SSH orchestration across a real fleet (the deferred fleet-control-plane epic, task [#1948](https://example.com/builders#/task/1948)); and *publishing* new patches, which stays a gated owner step (ADR 0134) — a follow-up task decides whether merges auto-publish.
 
 ## Gotchas

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.806",
+  "version": "1.19.807",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.806",
+      "version": "1.19.807",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.806",
+  "version": "1.19.807",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/routine-schedule.js

@@ -52,11 +52,49 @@ const WORKFLOWS_DIR = path.join(ROOT, '.github', 'workflows');
 
 const { parseRoutineFrontmatter } = require('./run-routine.js');
 
-// The cadences a routine may declare. The value is the period a cron expression
-// must resolve to for the two to agree. Add a name here and cronCadence() below
-// must be able to produce it, or the pair can never match.
+// The NAMED cadences a routine may declare. The value is the period a cron
+// expression must resolve to for the two to agree. Add a name here and
+// cronCadence() below must be able to produce it, or the pair can never match.
 const CADENCES = new Set(['hourly', 'daily', 'weekly', 'monthly']);
 
+// Sub-hourly cadences are open-ended rather than enumerated: '15min', '5min',
+// '30min'. Task 1003674 found the vocabulary topped out at `hourly`, so a
+// routine an operator wants to fire every 15 minutes could not SAY so — the
+// step cron that realizes it classified as unclassifiable and hard-failed the
+// check, which left "declare nothing and stay dormant" as the only green
+// option. That is the exact failure mode this file exists to refuse.
+//
+// N MUST DIVIDE 60. A cron step restarts each hour, so only a divisor of 60
+// yields a genuinely uniform period: `*/15` fires at :00 :15 :30 :45 (every 15
+// minutes, always), but `*/7` fires at :00 …:56 and then waits 4 — a "7min"
+// cadence that is not one. Refusing the non-divisors keeps the declared period
+// and the realized period the same claim.
+const SUBHOURLY_RE = /^([1-9]\d*)min$/;
+
+// The one definition of "is N a real sub-hourly period" — both the cadence NAME
+// ('15min') and the cron STEP (*/15) are validated through here, so the two can
+// never drift apart and disagree about the same number.
+function isUniformDivisor(n) {
+  return Number.isInteger(n) && n > 0 && n < 60 && 60 % n === 0;
+}
+
+function subhourlyMinutes(name) {
+  const m = SUBHOURLY_RE.exec(String(name == null ? '' : name));
+  if (!m) return null;
+  const n = Number(m[1]);
+  return isUniformDivisor(n) ? n : null;
+}
+
+// The validity predicate the check asks. Kept separate from CADENCES so the
+// named set stays a plain enumerable list for the error message.
+function isCadence(name) {
+  return CADENCES.has(name) || subhourlyMinutes(name) !== null;
+}
+
+// The minute-field step spelling, hoisted so it is compiled once rather than per
+// classified cron: `*/15` and the equivalent `0/15`.
+const STEP_RE = /^(?:\*|0)\/([1-9]\d*)$/;
+
 // Pure: classify a 5-field cron expression into the cadence it actually realizes.
 // Returns null for anything this vocabulary cannot describe (step values, lists,
 // ranges) — a cadence can then never "match" it, which is the safe direction: an
@@ -67,12 +105,25 @@ const CADENCES = new Set(['hourly', 'daily', 'weekly', 'monthly']);
 //   17   6    *   *   *   → daily    (a specific hour, every day)
 //   17   6    3   *   *   → monthly  (a specific day-of-month)
 //   17   *    *   *   *   → hourly   (a specific minute, every hour)
+//   */15 *    *   *   *   → 15min    (a uniform sub-hourly step)
 function cronCadence(expr) {
   const f = String(expr == null ? '' : expr).trim().split(/\s+/);
   if (f.length !== 5) return null;
   const [min, hour, dom, mon, dow] = f;
   const fixed = (v) => /^\d+$/.test(v);
   const any = (v) => v === '*';
+
+  // Sub-hourly: a step in the minute field with every coarser field wide open.
+  // (STEP_RE is module-scope — see above.)
+  // Anything narrower (a step confined to one hour, or to weekdays) is NOT the
+  // period it looks like, so it stays unclassifiable.
+  const step = STEP_RE.exec(min);
+  if (step) {
+    if (!(any(hour) && any(dom) && any(mon) && any(dow))) return null;
+    const n = Number(step[1]);
+    return isUniformDivisor(n) ? `${n}min` : null;
+  }
+
   if (!fixed(min)) return null;          // every cadence below pins the minute
   if (!any(mon)) return null;            // a specific month is a yearly shape
   if (any(hour)) return any(dom) && any(dow) ? 'hourly' : null;
@@ -145,8 +196,8 @@ function evaluate({ withCadence, withoutCadence }, workflows) {
   const wf = workflows || [];
 
   for (const r of withCadence) {
-    if (!CADENCES.has(r.cadence)) {
-      violations.push(`routine '${r.name}': unknown cadence "${r.cadence}" (want ${[...CADENCES].join('|')})`);
+    if (!isCadence(r.cadence)) {
+      violations.push(`routine '${r.name}': unknown cadence "${r.cadence}" (want ${[...CADENCES].join('|')}, or <N>min where N divides 60)`);
       continue;
     }
     const firing = wf.filter((w) => invokesRoutine(w.text, r.name, r.steps));
@@ -228,4 +279,5 @@ if (require.main === module) main();
 module.exports = {
   checkRoutineCadencesScheduled, evaluate, cronCadence, workflowCrons,
   invokesRoutine, readRoutines, readWorkflows, CADENCES,
+  isCadence, subhourlyMinutes, isUniformDivisor,
 };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.806'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.807'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/routine_schedule.mjs

@@ -50,13 +50,73 @@ test('cronCadence refuses what its vocabulary cannot describe, rather than guess
   // Unclassifiable must mean "never matches a declared cadence" — the safe
   // direction. A clever cron that silently counted as `weekly` would reopen
   // exactly the drift this check exists to catch.
-  for (const expr of ['*/5 * * * *', '0 6 * * 1-5', '0 6 * * 1,4', '0 0 1 1 *', '17 6 * *', '', 'nonsense']) {
+  for (const expr of ['0 6 * * 1-5', '0 6 * * 1,4', '0 0 1 1 *', '17 6 * *', '', 'nonsense']) {
     assert.equal(rs.cronCadence(expr), null, `${expr} should not classify`);
   }
   // A day-of-month AND day-of-week together is an OR in cron — neither period.
   assert.equal(rs.cronCadence('17 6 3 * 1'), null);
 });
 
+test('cronCadence classifies a uniform sub-hourly step (task 1003674)', () => {
+  // The vocabulary used to stop at `hourly`, so a routine meant to fire every
+  // 15 minutes had no way to declare it: the cron that realizes it read as
+  // unclassifiable and hard-failed, leaving "declare nothing, stay dormant" as
+  // the only green option — the state this check exists to refuse.
+  assert.equal(rs.cronCadence('*/15 * * * *'), '15min');
+  assert.equal(rs.cronCadence('*/5 * * * *'), '5min');
+  assert.equal(rs.cronCadence('*/30 * * * *'), '30min');
+  assert.equal(rs.cronCadence('0/15 * * * *'), '15min', 'the 0/N spelling is the same schedule');
+});
+
+test('cronCadence refuses a step that is not a true period (task 1003674)', () => {
+  // A cron step restarts every hour, so only a divisor of 60 is uniform:
+  // */7 fires at :00…:56 then waits 4. Calling that "7min" would be the same
+  // silent drift between declared and realized period the check is here for.
+  for (const expr of ['*/7 * * * *', '*/8 * * * *', '*/45 * * * *', '*/60 * * * *', '*/0 * * * *']) {
+    assert.equal(rs.cronCadence(expr), null, `${expr} is not a uniform period`);
+  }
+  // A step narrowed to one hour or one weekday is not the sub-hourly period it
+  // resembles — it only fires inside that window.
+  assert.equal(rs.cronCadence('*/15 6 * * *'), null);
+  assert.equal(rs.cronCadence('*/15 * * * 1'), null);
+});
+
+test('isCadence accepts the named periods and the divisor-of-60 Nmin form (task 1003674)', () => {
+  for (const ok of ['hourly', 'daily', 'weekly', 'monthly', '15min', '5min', '30min', '1min']) {
+    assert.equal(rs.isCadence(ok), true, `${ok} should be declarable`);
+  }
+  for (const no of ['7min', '60min', '90min', 'min', '0min', 'fortnightly', '', null, undefined]) {
+    assert.equal(rs.isCadence(no), false, `${no} should not be declarable`);
+  }
+});
+
+test('a routine declaring a sub-hourly cadence matches a step cron that fires it (task 1003674)', () => {
+  // End-to-end through evaluate(): declaring 15min is only green when a
+  // committed scheduler actually fires it at 15 minutes.
+  const wf = (cron) => [{
+    file: 'sweep.yml',
+    text: `on:\n  schedule:\n    - cron: '${cron}'\njobs:\n  go:\n    steps:\n      - run: node scripts/gds/run-routine.js sweepy\n`,
+  }];
+  const declared = routines([{ name: 'sweepy', cadence: '15min', steps: [] }]);
+  assert.deepEqual(rs.evaluate(declared, wf('*/15 * * * *')).violations, []);
+
+  // Wrong period, and the check names both sides rather than shrugging.
+  const drifted = rs.evaluate(declared, wf('17 6 * * *')).violations;
+  assert.equal(drifted.length, 1);
+  assert.match(drifted[0], /declares cadence: 15min/);
+  assert.match(drifted[0], /-> daily|→ daily/);
+
+  // A non-divisor step cannot satisfy it either — it classifies as nothing.
+  assert.match(rs.evaluate(declared, wf('*/7 * * * *')).violations[0], /unclassifiable/);
+});
+
+test('an undeclarable cadence is refused by name (task 1003674)', () => {
+  const v = rs.evaluate(routines([{ name: 'sweepy', cadence: '7min', steps: [] }]), []).violations;
+  assert.equal(v.length, 1);
+  assert.match(v[0], /unknown cadence "7min"/);
+  assert.match(v[0], /N divides 60/);
+});
+
 test('workflowCrons reads every cron a workflow declares, quoted or bare, ignoring trailing comments', () => {
   const y = ["  schedule:", "    - cron: '17 6 * * 1'", '    - cron: "0 3 * * *"', '    - cron: 5 * * * *  # bare + comment'].join('\n');
   assert.deepEqual(rs.workflowCrons(y), ['17 6 * * 1', '0 3 * * *', '5 * * * *']);