@blamejs/core 0.11.40 → 0.11.42

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.42 (2026-05-22) — **`b.calendar` JSCalendar Group objects (RFC 8984 §1.4.4).** Closes the v0.11.31 deferral on JSCalendar Group. `b.calendar.validate` now recognises `@type: "Group"` as a container envelope for multiple Event / Task / Note entries that share a logical name + categories. `b.calendar.toIcal` emits a single VCALENDAR wrap containing every entry's component in declared order (VEVENT for Event, VTODO for Task, VJOURNAL for Note). Group is JSCalendar-only — iCalendar has no envelope-level metadata for Group.name / Group.categories, so a Group's metadata is dropped on the iCal-side of a round-trip; operators preserving Group state across systems use the JSON-native surface. **Added:** *`@type: "Group"` envelope (RFC 8984 §1.4.4)* — A Group carries `uid`, `updated`, `entries` (required non-empty array), and optional `name`, `description`, `categories` (String-keyed Boolean set), and `source` (URI string). Entries are validated recursively — each entry must be a valid Event / Task / Note per its own type rules. Groups nesting Groups is refused (RFC 8984 does not define a nesting semantic). · *`b.calendar.toIcal` emits single VCALENDAR for Group* — When `@type === "Group"`, toIcal emits one BEGIN:VCALENDAR / END:VCALENDAR envelope containing every entry's component in declared order. The Group's own uid / updated / name / description / categories are NOT round-tripped to iCalendar (RFC 5545 has no envelope-level metadata for these); operators preserving Group state across a round-trip use the JSON-native JSCalendar surface. · *Refusal vocabulary* — New structured `CalendarError` codes: `calendar/bad-entries` (entries missing, empty, non-array, or any entry malformed / Group-typed), `calendar/bad-group` (entry-specific field like start / duration / due / progress / recurrenceRules set on the Group envelope), `calendar/bad-categories` (non-object categories or non-`true` value), `calendar/bad-source` (non-string source). · *`JSCAL_TYPES.Group` export* — `b.calendar.JSCAL_TYPES.Group === "Group"` exposes the discriminator string for operator-side type-dispatch. **References:** [RFC 8984 §1.4.4 (JSCalendar Group)](https://www.rfc-editor.org/rfc/rfc8984.html#section-1.4.4) · [RFC 5545 §3.4 (VCALENDAR envelope)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.4)
+
+- v0.11.41 (2026-05-21) — **`b.calendar.expandRecurrence` picks up BYSETPOS (RFC 5545 §3.3.10).** Closes the v0.11.31 deferral on BYSETPOS — the recurrence filter that picks the Nth candidate from a BY*-filtered set within a FREQ interval. Common operator patterns now work directly: `FREQ=MONTHLY;BYDAY=FR;BYSETPOS=-1` for last Friday of each month, `FREQ=MONTHLY;BYDAY=TU;BYSETPOS=2` for second Tuesday, `FREQ=YEARLY;BYMONTH=10;BYDAY=SU;BYSETPOS=1` for first Sunday of October (the DST-end announcement pattern). Supported for `FREQ=MONTHLY` / `YEARLY` / `WEEKLY` at day-granularity (time-of-day inherited from `start`). `FREQ=DAILY` + BYSETPOS is refused with `calendar/bad-recurrence` since the semantics aren't meaningful at sub-day frequency. **Added:** *`bySetPos` filter on RecurrenceRule* — `recurrenceRules[i].bySetPos: [1, -1, 2]` picks the listed positions from the BY*-filtered candidate set within each FREQ interval. Positive values are 1-indexed from the start of the period; negative values count from the end. Multiple positions emit per period (e.g. `[1, -1]` emits both the first and last matching day of each month). Out-of-range positions silently drop per RFC 5545's tolerant grammar. · *MONTHLY / YEARLY / WEEKLY support* — BYSETPOS expands within month / year / WKST-aligned-week boundaries. For each period, all day-level candidates that pass the existing BY* filters (byDay / byMonth / byMonthDay / byWeekNo / byYearDay) are enumerated, sorted ascending, then indexed by `bySetPos`. The expand loop's step budget (`MAX_EXPAND_INSTANCES * 366`) is shared across periods so the BYSETPOS path can't outrun the v0.11.31 DoS bound. · *DAILY frequency refused* — `FREQ=DAILY` + BYSETPOS throws `calendar/bad-recurrence` at expand time. The combination has no meaningful per-period set semantics (a day has no sub-day BY* set to pick from in the v1 day-granularity model). Operators with a sub-day BYSETPOS use case use `FREQ=HOURLY` semantics directly without BYSETPOS, or open an issue with the use case. **Security:** *Step budget shared with non-BYSETPOS path* — BYSETPOS enumeration decrements the same `MAX_EXPAND_INSTANCES * 366` step budget the non-BYSETPOS path uses, and the per-period day-loop has a hard 400-iteration safety cap (covers max-366-days in a leap year + slack). Adversarial events combining many rules + sparse BY* filters + BYSETPOS can't outpace the original single-rule DoS bound. **References:** [RFC 5545 §3.3.10 (RRULE — BYSETPOS)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.3.10) · [RFC 8984 §4.3.2 (JSCalendar RecurrenceRule)](https://www.rfc-editor.org/rfc/rfc8984.html#section-4.3.2)
+
 - v0.11.40 (2026-05-21) — **Wiki Docker default port moves from 8080 → 3008.** The `examples/wiki` Docker stack now defaults to port 3008 throughout — `WIKI_PORT`, the Dockerfile `EXPOSE` directive, the in-container HEALTHCHECK URL, the dev `docker-compose.yml` host mapping, the Caddy reverse-proxy upstream, and the `server.js` + `lib/build-app.js` code defaults. Production deployments (`docker-compose.prod.yml`) are operator-invisible since Caddy fronts the container on 80/443 — the upstream port is never exposed to the host. Dev users hitting the wiki container directly now use `http://localhost:3008`. Operators who set `WIKI_PORT` explicitly in their `.env` keep working unchanged. **Changed:** *Wiki default port 8080 → 3008* — Default `WIKI_PORT` moves from 8080 (HTTP-alt, frequently collides with Tomcat / Jenkins / Confluence / Spring-Boot defaults) to 3008 (IANA-unassigned, no service-convention collision). The new default applies consistently across: `examples/wiki/Dockerfile` (`ENV WIKI_PORT`, `EXPOSE`, HEALTHCHECK URL), `examples/wiki/server.js`, `examples/wiki/lib/build-app.js`, `examples/wiki/docker-compose.yml` (host mapping `3008:3008`), `examples/wiki/docker-compose.prod.yml` (internal-network expose), `examples/wiki/Caddyfile` (upstream resolver), `examples/wiki/README.md`, `examples/wiki/DEPLOY.md`. · *Operator action* — Dev users with `localhost:8080` bookmarks, curl scripts, host-firewall allowlists, or IDE port forwarders pointed at the wiki need to switch to `localhost:3008`. Operators who set `WIKI_PORT=8080` explicitly in their `.env` keep working unchanged. Production deployments behind Caddy see no change — the upstream port is internal-network only. **References:** [IANA Service Name and Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml)
 
 - v0.11.39 (2026-05-21) — **`b.calendar.expandRecurrence` honors multiple `recurrenceRules` (RFC 8984 §4.3.2).** Closes the v0.11.31 deferral on the multi-rule path. `expandRecurrence` now walks every entry in `event.recurrenceRules`, expands each rule independently against the same `start` anchor, and UNIONs the resulting instances (dedup + sorted ascending). Per-rule `count` caps apply per-rule per RFC 8984 §4.3.2; the global `max` / `MAX_EXPAND_INSTANCES` cap applies to the unioned set. The step budget (`MAX_EXPAND_INSTANCES * 366`) is shared across all rules in the same expand call so an N-rule fan-out can't amplify the worst-case loop past the single-rule bound. **Added:** *Multi-rule expansion + UNION* — `event.recurrenceRules` of length > 1 now expands every rule, not just the first. Each rule's stepping (frequency / interval / count / until / BY* filters) operates independently; the resulting ISO 8601 UTC instant strings dedupe via object-keyed set semantics, then sort ascending. The single-rule case is structurally unchanged — same step loop, same per-rule cap behaviour. · *Per-rule `count` applies per-rule (RFC 8984 §4.3.2)* — Two rules with `count: 3` and `count: 2` produce up to 5 instances in the unioned output (minus any timestamps that dedupe across rules), not 5 instances total across the rules. Matches RFC 8984 §4.3.2 phrasing: each Recurrence Rule's count is applied per rule. · *Global step budget shared across rules* — The `MAX_EXPAND_INSTANCES * 366` step budget (introduced in v0.11.31) now tracks across rules in the same expand call. A 4-rule event with sparse BY* filters can't accumulate 4× the single-rule worst-case work; the budget is depleted across the full rule set. **Security:** *DoS amplification across N rules bounded by the same step budget* — The step budget is shared (not per-rule), so adversarial multi-rule events can't bypass the v0.11.31 BY*-filter cap by stacking N rules with sparse filters. Sparse-filter rules still complete within the original 10-year `MAX_EXPAND_SPAN_MS` window cap. **Detectors:** *No new detector — covered by existing recurrence-test surface* — Multi-rule UNION + dedup + global step budget are exercised by three new tests in `test/layer-0-primitives/calendar.test.js` (multi-rule union, same-rule dedup, global max applied to union). No detector needed — the bug class is testable end-to-end and the test file IS the canonical regression surface. **References:** [RFC 8984 §4.3.2 (JSCalendar RecurrenceRule — multi-rule expansion)](https://www.rfc-editor.org/rfc/rfc8984.html#section-4.3.2) · [RFC 5545 §3.8.5.3 (iCalendar RRULE — semantics under composition)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.8.5.3)

package/lib/calendar.js

@@ -123,9 +123,9 @@ function validate(jsCal) {
       "b.calendar.validate: input must be a JSCalendar object");
   }
   var t = jsCal["@type"];
-  if (t !== JSCAL_TYPES.Event && t !== JSCAL_TYPES.Task && t !== JSCAL_TYPES.Note) {
+  if (t !== JSCAL_TYPES.Event && t !== JSCAL_TYPES.Task && t !== JSCAL_TYPES.Note && t !== JSCAL_TYPES.Group) {
     throw new CalendarError("calendar/bad-type",
-      "b.calendar.validate: @type must be 'Event' or 'Task' or 'Note' (got " + JSON.stringify(t) + ")");
+      "b.calendar.validate: @type must be 'Event', 'Task', 'Note' or 'Group' (got " + JSON.stringify(t) + ")");
   }
   if (typeof jsCal.uid !== "string" || jsCal.uid.length === 0) {
     throw new CalendarError("calendar/no-uid",
@@ -224,7 +224,68 @@ function validate(jsCal) {
         Object.keys(JSCAL_NOTE_STATUS).join(" | ") + " (RFC 5545 §3.8.1.11 VJOURNAL STATUS)");
     }
   }
-  if (jsCal.recurrenceRules !== undefined) {
+  if (t === JSCAL_TYPES.Group) {
+    // RFC 8984 §1.4.4 — a Group is a container envelope for multiple
+    // Event / Task / Note entries that share a logical name +
+    // categories. Group itself does not carry start / duration / due
+    // / progress — those live on the entries. `entries` MUST be a
+    // non-empty array; every entry MUST be a valid Event / Task /
+    // Note (Groups nesting Groups is refused — the spec does not
+    // define a nesting recursion semantic).
+    if (!Array.isArray(jsCal.entries) || jsCal.entries.length === 0) {
+      throw new CalendarError("calendar/bad-entries",
+        "b.calendar.validate: Group.entries MUST be a non-empty array (RFC 8984 §1.4.4)");
+    }
+    for (var gei = 0; gei < jsCal.entries.length; gei += 1) {
+      var entry = jsCal.entries[gei];
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        throw new CalendarError("calendar/bad-entries",
+          "b.calendar.validate: Group.entries[" + gei + "] MUST be an object");
+      }
+      var et = entry["@type"];
+      if (et !== JSCAL_TYPES.Event && et !== JSCAL_TYPES.Task && et !== JSCAL_TYPES.Note) {
+        throw new CalendarError("calendar/bad-entries",
+          "b.calendar.validate: Group.entries[" + gei + "].@type MUST be 'Event', 'Task' or 'Note' " +
+          "(got " + JSON.stringify(et) + ") — Groups do not nest");
+      }
+      // Recurse into each entry so per-type shape rules apply.
+      validate(entry);
+    }
+    if (jsCal.source !== undefined && typeof jsCal.source !== "string") {
+      throw new CalendarError("calendar/bad-source",
+        "b.calendar.validate: Group.source MUST be a string URI when present (RFC 8984 §1.4.4)");
+    }
+    if (jsCal.categories !== undefined) {
+      // Codex P1 — `typeof null === "object"` would let `categories:
+      // null` through this check, and the subsequent Object.keys
+      // throws a raw TypeError instead of a structured CalendarError.
+      // Refuse null explicitly so callers depending on the
+      // `calendar/bad-categories` refusal code stay stable.
+      if (jsCal.categories === null || typeof jsCal.categories !== "object" ||
+          Array.isArray(jsCal.categories)) {
+        throw new CalendarError("calendar/bad-categories",
+          "b.calendar.validate: Group.categories MUST be a String-keyed Boolean object (RFC 8984 §1.4.4)");
+      }
+      var catKeys = Object.keys(jsCal.categories);
+      for (var ci = 0; ci < catKeys.length; ci += 1) {
+        if (jsCal.categories[catKeys[ci]] !== true) {
+          throw new CalendarError("calendar/bad-categories",
+            "b.calendar.validate: Group.categories['" + catKeys[ci] + "'] MUST be `true` (boolean set per RFC 8984 §1.4.4)");
+        }
+      }
+    }
+    // Group itself MUST NOT carry the entry-specific fields. Refuse
+    // explicit setting so operators don't accidentally model entry
+    // state on the envelope.
+    if (jsCal.start !== undefined || jsCal.duration !== undefined || jsCal.due !== undefined ||
+        jsCal.progress !== undefined || jsCal.percentComplete !== undefined ||
+        jsCal.progressUpdated !== undefined || jsCal.recurrenceRules !== undefined) {
+      throw new CalendarError("calendar/bad-group",
+        "b.calendar.validate: Group MUST NOT carry start / duration / due / progress / " +
+        "percentComplete / progressUpdated / recurrenceRules — those live on the entries");
+    }
+  }
+  if (t !== JSCAL_TYPES.Group && jsCal.recurrenceRules !== undefined) {
     if (!Array.isArray(jsCal.recurrenceRules)) {
       throw new CalendarError("calendar/bad-recurrence",
         "b.calendar.validate: recurrenceRules MUST be an array of RecurrenceRule");
@@ -243,7 +304,7 @@ function validate(jsCal) {
     }
   }
   if (jsCal.alerts !== undefined) {
-    if (typeof jsCal.alerts !== "object" || Array.isArray(jsCal.alerts)) {
+    if (jsCal.alerts === null || typeof jsCal.alerts !== "object" || Array.isArray(jsCal.alerts)) {
       throw new CalendarError("calendar/bad-alerts",
         "b.calendar.validate: alerts MUST be an object map keyed by alert-id");
     }
@@ -328,6 +389,33 @@ function fromIcal(text, opts) {
 function toIcal(jsCal, opts) {
   validate(jsCal);
   var prodid = (opts && opts.prodid) || "-//blamejs//Calendar//EN";
+  // RFC 8984 §1.4.4 — a Group emits a single VCALENDAR envelope
+  // containing every entry's component in declared order. The Group's
+  // own uid + updated + name + description are NOT round-tripped to
+  // iCalendar (RFC 5545 has no envelope-level metadata for these);
+  // operators preserving Group metadata across a round-trip use the
+  // JSON-native JSCalendar surface.
+  if (jsCal["@type"] === "Group") {
+    var groupLines = [
+      "BEGIN:VCALENDAR",
+      "VERSION:2.0",
+      "PRODID:" + prodid,
+    ];
+    for (var gei2 = 0; gei2 < jsCal.entries.length; gei2 += 1) {
+      var entryIcal = toIcal(jsCal.entries[gei2], { prodid: prodid });
+      // Strip outer VCALENDAR envelope; keep inner component lines.
+      var entryLines = entryIcal.split("\r\n");
+      for (var eli = 0; eli < entryLines.length; eli += 1) {
+        var line = entryLines[eli];
+        if (line && line !== "BEGIN:VCALENDAR" && line !== "VERSION:2.0" &&
+            line.indexOf("PRODID:") !== 0 && line !== "END:VCALENDAR") {
+          groupLines.push(line);
+        }
+      }
+    }
+    groupLines.push("END:VCALENDAR");
+    return groupLines.join("\r\n") + "\r\n";
+  }
   // RFC 8984 §6 — JSCalendar Task maps to RFC 5545 §3.6.2 VTODO; Event
   // maps to VEVENT. The wrapper + most properties are identical; the
   // wrapping component tag + Task-specific fields (DUE / STATUS /
@@ -425,13 +513,14 @@ function toIcal(jsCal, opts) {
  *
  * v1 supports FREQ=DAILY/WEEKLY/MONTHLY/YEARLY with INTERVAL, COUNT,
  * UNTIL. BYDAY / BYMONTH / BYMONTHDAY / BYWEEKNO / BYYEARDAY /
- * BYHOUR / BYMINUTE / BYSECOND refine the base frequency. Multiple
+ * BYHOUR / BYMINUTE / BYSECOND refine the base frequency. BYSETPOS
+ * picks the Nth candidate from the BY*-filtered set within a FREQ
+ * interval (positive = 1-indexed from start, negative = from end);
+ * supported for FREQ=MONTHLY / YEARLY / WEEKLY with day-granularity
+ * candidates (time-of-day inherited from start). Multiple
  * `recurrenceRules` are expanded independently and UNIONed; per
  * RFC 8984 §4.3.2 each rule's `count` cap applies per-rule, not to
- * the combined set. BYSETPOS remains deferred-with-condition
- * (requires expanding ALL candidates within a FREQ interval and
- * picking the Nth — a structural restructure of the step loop;
- * RFC 7529 non-Gregorian calendars not in scope either).
+ * the combined set. (RFC 7529 non-Gregorian calendars not in scope.)
  *
  * @opts
  *   from: string,    // ISO 8601 UTC timestamp — lower bound of expansion window
@@ -645,6 +734,36 @@ function _expandSingleRule(rule, startMs, ctx) {
     if (bySecondSet && !bySecondSet[d.getUTCSeconds()]) return false;
     return true;
   }
+  // RFC 5545 §3.3.10 BYSETPOS — picks the Nth candidate from the
+  // BY*-filtered set within a FREQ interval. Positive = 1-indexed
+  // from start; negative = from end. Operators reach for this most
+  // often with "last Friday of month" (FREQ=MONTHLY;BYDAY=FR;
+  // BYSETPOS=-1) or "second Tuesday of month" (BYSETPOS=2).
+  //
+  // v1 supports BYSETPOS for FREQ=MONTHLY / YEARLY / WEEKLY at
+  // day-granularity — candidates are days within the period at the
+  // start's time-of-day. Sub-day BY* filters (byHour/byMinute/
+  // bySecond) are ignored under BYSETPOS for v1; the rare combo
+  // (BYSETPOS + byHour) reverts to the standard non-bysetpos step
+  // path when applicable.
+  var bySetPosArr = _bySetPosArray(rule.bySetPos);
+  if (bySetPosArr) {
+    return _expandWithBysetpos({
+      rule:         rule,
+      startMs:      startMs,
+      freq:         freq,
+      interval:     interval,
+      count:        count,
+      untilMs:      untilMs,
+      fromMs:       fromMs,
+      toMs:         toMs,
+      maxCount:     maxCount,
+      matchesBy:    _matchesBy,
+      bySetPos:     bySetPosArr,
+      stepBudgetRef: ctx.stepBudgetRef,
+    });
+  }
+
   var t = startMs;
   // Safety cap on the step loop: at most MAX_EXPAND_INSTANCES * 366
   // iterations so BY* filters that match sparsely (e.g. FREQ=DAILY;
@@ -670,6 +789,139 @@ function _expandSingleRule(rule, startMs, ctx) {
   return { instances: out, stepBudgetRemaining: ctx.stepBudgetRef.remaining };
 }
 
+// Parse + validate rule.bySetPos. Returns null when absent / empty;
+// otherwise an array of integers in [-366, -1] U [1, 366] (RFC 5545
+// grammar). Zero values + out-of-range values are silently dropped.
+function _bySetPosArray(raw) {
+  if (!Array.isArray(raw) || raw.length === 0) return null;
+  var out = [];
+  for (var i = 0; i < raw.length; i += 1) {
+    var n = parseInt(raw[i], 10);
+    if (isFinite(n) && n !== 0 && n >= -366 && n <= 366) out.push(n);                                  // allow:raw-byte-literal — RFC 5545 §3.3.10 bysetpos range
+  }
+  return out.length > 0 ? out : null;
+}
+
+// BYSETPOS expander. Iterates by FREQ interval; for each period,
+// enumerates day-level candidates within the period; applies the
+// caller's matchesBy filter; sorts ascending; picks the position(s)
+// per bySetPos. Time-of-day per candidate matches the rule's start.
+function _expandWithBysetpos(ctx) {
+  var startMs      = ctx.startMs;
+  var freq         = ctx.freq;
+  var interval     = ctx.interval;
+  var count        = ctx.count;
+  var untilMs      = ctx.untilMs;
+  var fromMs       = ctx.fromMs;
+  var toMs         = ctx.toMs;
+  var maxCount     = ctx.maxCount;
+  var matchesBy    = ctx.matchesBy;
+  var bySetPos     = ctx.bySetPos;
+  var stepBudgetRef = ctx.stepBudgetRef;
+
+  if (freq !== "monthly" && freq !== "yearly" && freq !== "weekly") {
+    throw new CalendarError("calendar/bad-recurrence",
+      "b.calendar.expandRecurrence: BYSETPOS supported only with FREQ=MONTHLY / YEARLY / WEEKLY (got '" + freq + "')");
+  }
+
+  var startDate = new Date(startMs);
+  var hh = startDate.getUTCHours();
+  var mm = startDate.getUTCMinutes();
+  var ss = startDate.getUTCSeconds();
+  var ms = startDate.getUTCMilliseconds();
+
+  var out = [];
+  // Period anchor (period 0 = start's period).
+  var periodIndex = 0;
+
+  while (out.length < count && out.length < maxCount && stepBudgetRef.remaining > 0) {
+    var period = _periodForIndex(freq, startDate, periodIndex * interval);
+    periodIndex += 1;
+    // Out-of-window early exit. Window-uppper applies once the period
+    // start crosses toMs; until applies once period-start crosses untilMs.
+    if (period.startMs > untilMs) break;
+    if (toMs !== null && period.startMs > toMs) break;
+
+    // Enumerate day-level candidates within the period at start's
+    // time-of-day. The budget decrements per candidate so adversarial
+    // periods (e.g. YEARLY = 366 days) can't loop forever.
+    var candidates = [];
+    var dayMs = period.startMs;
+    var safety = 400;                                                                                  // allow:raw-byte-literal — period day cap (covers leap year 366 + slack)
+    while (dayMs <= period.endMs && safety-- > 0 && stepBudgetRef.remaining > 0) {
+      stepBudgetRef.remaining -= 1;
+      var candidate = _withTimeOfDay(dayMs, hh, mm, ss, ms);
+      if (matchesBy(candidate)) candidates.push(candidate);
+      dayMs += 86400000;                                                                               // allow:raw-time-literal — 86400000 ms/day step // allow:raw-byte-literal — same constant in ms/day form
+    }
+
+    // Sort + apply BYSETPOS. Positive index 1-based from start;
+    // negative from end. Out-of-range positions silently drop.
+    candidates.sort(function (a, b) { return a - b; });
+    var picked = Object.create(null);
+    for (var pi = 0; pi < bySetPos.length; pi += 1) {
+      var pos = bySetPos[pi];
+      var idx = pos > 0 ? pos - 1 : candidates.length + pos;
+      if (idx >= 0 && idx < candidates.length) picked[candidates[idx]] = true;
+    }
+    // Emit picked candidates in ascending order, gated by window +
+    // untilMs + per-rule count cap.
+    //
+    // Codex P1 — recurrence instances MUST NOT precede DTSTART (per
+    // RFC 5545 §3.8.5.3). The period-boundary enumeration above
+    // includes candidates BEFORE startMs when the period containing
+    // startMs has earlier BY*-matching days (e.g. start = May 20
+    // Friday, BYDAY=FR;BYSETPOS=1 → enumeration would pick May 1).
+    // Refusing pre-start candidates here both fixes the semantics
+    // AND avoids consuming the per-rule COUNT cap on instances the
+    // operator never asked for.
+    var pickedKeys = Object.keys(picked).map(Number).sort(function (a, b) { return a - b; });
+    for (var ki = 0; ki < pickedKeys.length; ki += 1) {
+      var pickedMs = pickedKeys[ki];
+      if (pickedMs < startMs) continue;
+      if (pickedMs > untilMs) { count = out.length; break; }
+      if (toMs !== null && pickedMs > toMs) { count = out.length; break; }
+      if (fromMs !== null && pickedMs < fromMs) continue;
+      if (out.length >= count || out.length >= maxCount) break;
+      out.push(_msToIsoZ(pickedMs));
+    }
+  }
+  return { instances: out, stepBudgetRemaining: stepBudgetRef.remaining };
+}
+
+// Compute period [startMs, endMs] given a base start date + interval
+// offset. Period START is anchored at the first second of the period
+// (Jan 1 for YEARLY, day 1 for MONTHLY, WKST-Monday for WEEKLY) so
+// the day-enumeration loop strides whole-day from there.
+function _periodForIndex(freq, startDate, offset) {
+  if (freq === "yearly") {
+    var year = startDate.getUTCFullYear() + offset;
+    var ys = Date.UTC(year, 0, 1, 0, 0, 0, 0);
+    var ye = Date.UTC(year + 1, 0, 1, 0, 0, 0, 0) - 1;
+    return { startMs: ys, endMs: ye };
+  }
+  if (freq === "monthly") {
+    var bm = startDate.getUTCMonth() + offset;
+    var by = startDate.getUTCFullYear() + Math.floor(bm / 12);                                         // allow:raw-byte-literal — months/year
+    var mm = ((bm % 12) + 12) % 12;                                                                    // allow:raw-byte-literal — months/year
+    var ms = Date.UTC(by, mm, 1, 0, 0, 0, 0);
+    var me = Date.UTC(by, mm + 1, 1, 0, 0, 0, 0) - 1;
+    return { startMs: ms, endMs: me };
+  }
+  // weekly — align to WKST=Monday (RFC 5545 default WKST).
+  var anchor = new Date(Date.UTC(startDate.getUTCFullYear(), startDate.getUTCMonth(), startDate.getUTCDate(), 0, 0, 0, 0));
+  var dow = anchor.getUTCDay() || 7;
+  anchor.setUTCDate(anchor.getUTCDate() - (dow - 1) + offset * 7);                                     // allow:raw-byte-literal — days/week
+  var ws = anchor.getTime();
+  var we = ws + 7 * 86400000 - 1;                                                                      // allow:raw-byte-literal + allow:raw-time-literal — 7-day window
+  return { startMs: ws, endMs: we };
+}
+
+function _withTimeOfDay(dayMs, hh, mm, ss, ms) {
+  var d = new Date(dayMs);
+  return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), hh, mm, ss, ms);
+}
+
 // ---- Internal helpers ----------------------------------------------------
 
 function _veventToJsCalEvent(ve) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.40",
+  "version": "0.11.42",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:1f82638d-96d9-44e6-9642-4d336ee1d858",
+  "serialNumber": "urn:uuid:7f569328-85b0-4395-b846-ba8cf2a95b3b",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-22T00:19:00.297Z",
+    "timestamp": "2026-05-22T02:30:35.680Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.40",
+      "bom-ref": "@blamejs/core@0.11.42",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.40",
+      "version": "0.11.42",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.40",
+      "purl": "pkg:npm/%40blamejs/core@0.11.42",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.40",
+      "ref": "@blamejs/core@0.11.42",
       "dependsOn": []
     }
   ]