@blamejs/core 0.11.40 → 0.11.41

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- 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

@@ -425,13 +425,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 +646,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 +701,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.41",
   "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:5557c11a-5977-46f0-8a4f-c25e3b621e70",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-22T00:19:00.297Z",
+    "timestamp": "2026-05-22T01:26:53.795Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.40",
+      "bom-ref": "@blamejs/core@0.11.41",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.40",
+      "version": "0.11.41",
       "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.41",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.40",
+      "ref": "@blamejs/core@0.11.41",
       "dependsOn": []
     }
   ]