@blamejs/core 0.11.35 → 0.11.37

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.37 (2026-05-21) — **`b.calendar` VJOURNAL ↔ JSCalendar Note (RFC 5545 §3.6.3).** Closes the v0.11.31 deferral on VJOURNAL. `b.calendar.fromIcal` now recognises VJOURNAL components and maps them to JSCalendar-shaped Note objects (`@type: "Note"`). `b.calendar.toIcal` emits a VJOURNAL envelope when the input `@type` is `Note`. `b.calendar.validate` adds Note-specific shape rules: optional `start` LocalDateTime, no `duration` / `due` / `progress` / `percentComplete` / `progressUpdated` (those are Event / Task-only properties), optional `status` from the RFC 5545 §3.8.1.11 VJOURNAL vocabulary (`draft` | `final` | `cancelled`). VJOURNAL is the only iCalendar component that may carry multiple DESCRIPTION properties — Note preserves operator-visible boundaries by joining them with a blank-line separator. A VCALENDAR carrying VEVENT + VTODO + VJOURNAL children now returns a mixed `Event` + `Task` + `Note` array. **Added:** *`b.calendar.fromIcal` maps VJOURNAL → JSCalendar Note* — VJOURNAL components in the VCALENDAR map to `@type: "Note"` objects with `uid` / `updated` / `title` (SUMMARY) / `description` (DESCRIPTION) / `start` (DTSTART → LocalDateTime, optional) / `timeZone` / `status` (lower-cased STATUS) / `locations` / `recurrenceRules`. UTC DTSTART maps to `timeZone: "Etc/UTC"` the same way DTSTART does for Event. · *`b.calendar.toIcal` emits VJOURNAL when `@type === "Note"`* — The envelope is `BEGIN:VJOURNAL` / `END:VJOURNAL` instead of `BEGIN:VEVENT` or `BEGIN:VTODO`. Note's `status` round-trips uppercased per RFC 5545 §3.8.1.11. Note does NOT emit DURATION / DUE / PERCENT-COMPLETE / COMPLETED on the wire (those properties are forbidden on VJOURNAL per RFC 5545 §3.6.3 grammar). · *`b.calendar.validate` learns Note-specific shape rules (RFC 5545 §3.6.3)* — Note's `start` must be a LocalDateTime when present. Setting `duration`, `due`, `progress`, `percentComplete`, or `progressUpdated` on a Note is refused (those are Event / Task-only properties). `status` must be in the `JSCAL_NOTE_STATUS` catalogue (`draft` | `final` | `cancelled` — different from the Task progress vocabulary). Structured `CalendarError` codes: `calendar/bad-note-status` plus reuse of `calendar/bad-due`, `calendar/bad-progress`, `calendar/bad-duration`, `calendar/bad-percent`, `calendar/bad-progress-updated` for the forbidden-property refusals. · *Multiple DESCRIPTION properties preserved* — VJOURNAL is the only iCalendar component permitted to carry multiple DESCRIPTION properties (one per discrete journal entry). `fromIcal` joins them into a single Note.description with `\n\n` between entries, preserving the operator-visible boundary. Single-DESCRIPTION VJOURNALs map to the literal string with no join. · *Mixed-component VCALENDAR returns array of Event + Task + Note shapes* — A VCALENDAR carrying VEVENT + VTODO + VJOURNAL children now returns an Array — events first, tasks second, journals third, in their declared order. The single-component shortcut (returning the bare object) still applies when only one component is present. · *`JSCAL_TYPES.Note` and `JSCAL_NOTE_STATUS` exports* — `b.calendar.JSCAL_TYPES.Note === "Note"` (the discriminator string). `b.calendar.JSCAL_NOTE_STATUS` exposes the `draft` / `final` / `cancelled` vocabulary as a frozen object for operator-side enum lookups. **Changed:** *JSCalendar `Note` is a blamejs-recognised extension* — RFC 8984 §1.2 only enumerates `Event`, `Task`, and `Group` as discriminator values. `Note` is not formally an RFC 8984 type — blamejs adopts it as a recognised extension shape for VJOURNAL round-trip interop. Operators interoperating with strict RFC 8984 consumers should map Note → Group + a vendor-namespaced property before exchange. **References:** [RFC 5545 §3.6.3 (iCalendar VJOURNAL component)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.6.3) · [RFC 5545 §3.8.1.11 (STATUS — DRAFT/FINAL/CANCELLED on VJOURNAL)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.8.1.11) · [RFC 8984 §1.2 (JSCalendar @type discriminator)](https://www.rfc-editor.org/rfc/rfc8984.html#section-1.2)
+
+- v0.11.36 (2026-05-21) — **`b.calendar.expandRecurrence` picks up BYWEEKNO / BYYEARDAY / BYHOUR / BYMINUTE / BYSECOND filters (RFC 5545 §3.3.10).** Closes the v0.11.31 deferral on the time-of-day and year-relative BY* filters. `expandRecurrence` now honours `byWeekNo` (ISO 8601 1..53 with negative-from-end semantics), `byYearDay` (1..366 with negative-from-end), `byHour` (0..23), `byMinute` (0..59), and `bySecond` (0..60 — covers POSIX leap-second representation). The expansion still operates as a per-step filter (stepping at the rule's FREQ, then dropping candidates that fail the BY* predicates) — BYSETPOS remains deferred-with-condition because it requires expanding ALL candidates within a FREQ interval and picking the Nth, which is a structural restructure of the expand loop. Operators with `last weekday of month`-style needs continue to see the same defer note from v0.11.31. **Added:** *`byWeekNo` filter — ISO 8601 week numbers* — `recurrenceRules[i].byWeekNo: [1, 53, -1]` filters candidates to the named ISO 8601 weeks. Negative values count from the end of the year (`-1` = last ISO week, which may be week 52 or week 53 depending on the year). The ISO week-of-year calculation matches the canonical algorithm — week 1 is the week containing the first Thursday of the year. · *`byYearDay` filter — day-of-year (1..366 / -1..-366)* — `recurrenceRules[i].byYearDay: [1, 366, -1]` filters by ordinal day-of-year. Negative values count from the end of the year, accounting for leap-year length (366 vs 365). With a `frequency: "daily"` rule + `byYearDay: [1]` the expander emits Jan 1 of each year. · *`byHour` / `byMinute` / `bySecond` time-of-day filters* — `byHour: [9, 17]` filters candidates by UTC hour-of-day (0..23). `byMinute: [0, 30]` (0..59). `bySecond: [0, 30, 60]` (0..60 — the leap-second representation in POSIX time). Most useful with sub-day frequencies — `frequency: "hourly"` + `byHour: [9, 17]` emits twice-daily at 9am and 5pm. · *Negative BY* semantics per RFC 5545 §3.3.10* — `byWeekNo: [-1]` matches the last ISO week of the year (computed via the Dec-28 anchor — Dec 28 always falls in the last ISO week). `byYearDay: [-1]` matches the last day of the year (uses the Gregorian leap-year rule to determine whether 365 or 366 is the correct ordinal). Both negative-value paths covered by tests. **Security:** *Same step-budget cap from v0.11.31 applies* — Sparse BY* filters (e.g. `byYearDay: [1]` with `frequency: "daily"` — only 1 in 365 candidates matches) still loop within the `MAX_EXPAND_INSTANCES * 366` step budget; the 10-year `MAX_EXPAND_SPAN_MS` window cap also applies. Operators can't construct a BY*-filter that loops past the bounded budget. · *Integer-range validation on every BY* value* — `byWeekNo` rejects values outside ±53. `byYearDay` rejects outside ±366. `byHour` 0..23. `byMinute` 0..59. `bySecond` 0..60. Adversarial-shape values silently drop from the set (no error — the rule continues with the surviving values per RFC 5545's tolerant grammar). **References:** [RFC 5545 §3.3.10 (RRULE — BYWEEKNO / BYYEARDAY / BYHOUR / BYMINUTE / BYSECOND)](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) · [ISO 8601 (Week numbering)](https://www.iso.org/iso-8601-date-and-time-format.html)
+
 - v0.11.35 (2026-05-21) — **`b.calendar` VTODO ↔ JSCalendar Task (RFC 8984 §6).** Closes the v0.11.31 deferral. `b.calendar.fromIcal` now recognises VTODO components and maps them to JSCalendar Task objects per RFC 8984 §6. `b.calendar.toIcal` emits a VTODO envelope (with DUE / STATUS / PERCENT-COMPLETE / COMPLETED iCalendar properties) when the input `@type` is `Task`. `b.calendar.validate` picks up Task-specific shape rules: `due` as LocalDateTime, `estimatedDuration` as PnYnMnDTnHnMnS, `progress` from the RFC 8984 §6.4.3 vocabulary (`needs-action` | `in-process` | `completed` | `cancelled` | `failed`), `percentComplete` ∈ [0..100], `progressUpdated` as UTCDateTime. A VCALENDAR carrying both VEVENT and VTODO components now returns an array of mixed `Event` + `Task` shapes. **Added:** *`b.calendar.fromIcal` maps VTODO → JSCalendar Task* — VTODO components in the VCALENDAR are mapped to `@type: "Task"` objects with the same `uid` / `updated` / `title` / `description` / `start` / `timeZone` / `locations` / `recurrenceRules` slots Event uses, plus the Task-specific fields: `due` (DUE → LocalDateTime), `estimatedDuration` (DURATION), `progress` (STATUS lowercased), `percentComplete` (PERCENT-COMPLETE 0..100), `progressUpdated` (COMPLETED → UTCDateTime). UTC DUE values map to `timeZone: "Etc/UTC"` the same way DTSTART does. · *`b.calendar.toIcal` emits VTODO when `@type === "Task"`* — The envelope is `BEGIN:VTODO` / `END:VTODO` instead of `BEGIN:VEVENT`. Task-specific properties round-trip: `DUE` (with `;TZID=` parameter or `Z` suffix or floating local time per the same RFC 8984 §1.4.4 timeZone mapping as DTSTART), `STATUS` (uppercased), `PERCENT-COMPLETE`, `COMPLETED` (UTC). `estimatedDuration` maps to `DURATION` (RFC 5545 doesn't distinguish Event vs Task duration on the wire). · *`b.calendar.validate` learns Task-specific shape rules (RFC 8984 §6.4)* — `due` must be a LocalDateTime, `estimatedDuration` must match the same PnYnMnDTnHnMnS Duration grammar Event uses, `progress` must be in the `JSCAL_TASK_PROGRESS` catalogue (also exposed as a new top-level export), `percentComplete` must be a finite number in 0..100, `progressUpdated` must be a UTCDateTime. Structured `CalendarError` codes: `calendar/bad-due`, `calendar/bad-progress`, `calendar/bad-percent`, `calendar/bad-progress-updated`. · *Mixed-component VCALENDAR returns an array of Event + Task shapes* — When a VCALENDAR contains both VEVENT and VTODO children, `fromIcal` returns an Array — events first, tasks second, in their declared order. The single-component shortcut (returning the bare object) still applies when only one component is present. · *`calendar/no-vevent` error code renamed to `calendar/no-component`* — The refusal that fires when a VCALENDAR has no parseable child component now uses the more accurate `calendar/no-component` code (since VTODO is also valid). Operators that grep on the prior `calendar/no-vevent` code need to update the match; the human-facing error message also updates. **References:** [RFC 8984 §6 (JSCalendar Task)](https://www.rfc-editor.org/rfc/rfc8984.html#section-6) · [RFC 5545 §3.6.2 (iCalendar VTODO component)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.6.2) · [RFC 5545 §3.8.2.3 (DUE date-time)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.8.2.3) · [RFC 5545 §3.8.1.11 (STATUS — needs-action/in-process/completed/cancelled)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.8.1.11)
 
 - v0.11.34 (2026-05-21) — **JMAP WebSocket transport (RFC 8887) on `b.mail.server.jmap`.** Closes the v0.11.29 deferral. The JMAP listener now exposes `webSocketHandler(req, socket, head)` — a turnkey RFC 8887 transport built on the framework's `b.websocket.handleUpgrade`. Clients connect with the `jmap` subprotocol; bidirectional JSON frames carry `{ "@type": "Request" }` / `{ "@type": "WebSocketPushEnable" }` / `{ "@type": "WebSocketPushDisable" }` from the client, and `{ "@type": "Response" }` / `{ "@type": "StateChange" }` / `{ "@type": "RequestError" }` from the server. `Request` frames flow through the same `dispatch(actor, request)` path the HTTP `apiHandler` uses; `WebSocketPushEnable` hooks the operator's `mailStore.subscribePush(actor, types, emitFn)` and converts backend StateChange events into outbound WebSocket frames.

package/lib/calendar.js

@@ -42,6 +42,14 @@ var CalendarError = defineClass("CalendarError", { alwaysPermanent: true });
 var JSCAL_TYPES = Object.freeze({
   Event:        "Event",
   Task:         "Task",
+  // Note maps RFC 5545 §3.6.3 VJOURNAL — a dated, free-form journal
+  // entry with no duration / progress / due semantics. Not formally
+  // defined as an @type in RFC 8984 §1.2 (which only enumerates
+  // Event + Task + Group); blamejs adopts `Note` as a recognised
+  // extension shape for VJOURNAL round-trip interop with iCalendar
+  // sources. Operators interoperating with strict RFC 8984 consumers
+  // should map Note → Group or Note → custom-@type before exchange.
+  Note:         "Note",
   Group:        "Group",
   Participant:  "Participant",
   Location:     "Location",
@@ -73,6 +81,15 @@ var JSCAL_TASK_PROGRESS = Object.freeze({
   "needs-action": 1, "in-process": 1, "completed": 1, "cancelled": 1,
 });
 
+// RFC 5545 §3.8.1.11 STATUS for VJOURNAL — Note carries DRAFT / FINAL
+// / CANCELLED. JSCalendar lower-cases them on import/export. Note's
+// `status` is OPTIONAL; absence on the wire maps to `status`
+// unset (rather than defaulting to "draft" — operator intent is
+// ambiguous when STATUS is omitted, per RFC 5545 grammar).
+var JSCAL_NOTE_STATUS = Object.freeze({
+  "draft": 1, "final": 1, "cancelled": 1,
+});
+
 // Recurrence-expansion caps. Mirror b.safeIcal's RRULE limits so the
 // expand path can't outpace what the parser already permitted.
 var MAX_EXPAND_INSTANCES = 4096;                                                                       // allow:raw-byte-literal — instance count cap, not bytes
@@ -106,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) {
+  if (t !== JSCAL_TYPES.Event && t !== JSCAL_TYPES.Task && t !== JSCAL_TYPES.Note) {
     throw new CalendarError("calendar/bad-type",
-      "b.calendar.validate: @type must be 'Event' or 'Task' (got " + JSON.stringify(t) + ")");
+      "b.calendar.validate: @type must be 'Event' or 'Task' or 'Note' (got " + JSON.stringify(t) + ")");
   }
   if (typeof jsCal.uid !== "string" || jsCal.uid.length === 0) {
     throw new CalendarError("calendar/no-uid",
@@ -170,6 +187,43 @@ function validate(jsCal) {
         "b.calendar.validate: Task.progressUpdated MUST be a UTCDateTime");
     }
   }
+  if (t === JSCAL_TYPES.Note) {
+    // Note (VJOURNAL) — dated free-form journal entry. RFC 5545
+    // §3.6.3 permits an optional DTSTART (date or date-time) and
+    // SUMMARY / DESCRIPTION; STATUS values are limited to DRAFT /
+    // FINAL / CANCELLED. There is no DUE / DURATION / COMPLETED /
+    // PERCENT-COMPLETE on VJOURNAL.
+    if (jsCal.start !== undefined && (typeof jsCal.start !== "string" || !_isLocalDateTime(jsCal.start))) {
+      throw new CalendarError("calendar/bad-start",
+        "b.calendar.validate: Note.start MUST be a LocalDateTime (RFC 5545 §3.6.3)");
+    }
+    if (jsCal.duration !== undefined) {
+      throw new CalendarError("calendar/bad-duration",
+        "b.calendar.validate: Note.duration MUST NOT be set (RFC 5545 §3.6.3 VJOURNAL has no DURATION)");
+    }
+    if (jsCal.due !== undefined) {
+      throw new CalendarError("calendar/bad-due",
+        "b.calendar.validate: Note.due MUST NOT be set (DUE is a VTODO-only property)");
+    }
+    if (jsCal.progress !== undefined) {
+      throw new CalendarError("calendar/bad-progress",
+        "b.calendar.validate: Note.progress MUST NOT be set (progress is a Task-only property)");
+    }
+    if (jsCal.percentComplete !== undefined) {
+      throw new CalendarError("calendar/bad-percent",
+        "b.calendar.validate: Note.percentComplete MUST NOT be set (percentComplete is a Task-only property)");
+    }
+    if (jsCal.progressUpdated !== undefined) {
+      throw new CalendarError("calendar/bad-progress-updated",
+        "b.calendar.validate: Note.progressUpdated MUST NOT be set (progressUpdated is a Task-only property)");
+    }
+    if (jsCal.status !== undefined &&
+        !Object.prototype.hasOwnProperty.call(JSCAL_NOTE_STATUS, jsCal.status)) {
+      throw new CalendarError("calendar/bad-note-status",
+        "b.calendar.validate: Note.status MUST be one of " +
+        Object.keys(JSCAL_NOTE_STATUS).join(" | ") + " (RFC 5545 §3.8.1.11 VJOURNAL STATUS)");
+    }
+  }
   if (jsCal.recurrenceRules !== undefined) {
     if (!Array.isArray(jsCal.recurrenceRules)) {
       throw new CalendarError("calendar/bad-recurrence",
@@ -234,14 +288,16 @@ function validate(jsCal) {
  */
 function fromIcal(text, opts) {
   var ast = safeIcal.parse(text, opts || {});
-  var events = (ast && ast.vcalendar && ast.vcalendar.vevent) || [];
-  var todos  = (ast && ast.vcalendar && ast.vcalendar.vtodo)  || [];
-  if (events.length === 0 && todos.length === 0) {
+  var events   = (ast && ast.vcalendar && ast.vcalendar.vevent)   || [];
+  var todos    = (ast && ast.vcalendar && ast.vcalendar.vtodo)    || [];
+  var journals = (ast && ast.vcalendar && ast.vcalendar.vjournal) || [];
+  if (events.length === 0 && todos.length === 0 && journals.length === 0) {
     throw new CalendarError("calendar/no-component",
-      "b.calendar.fromIcal: VCALENDAR has no VEVENT or VTODO components");
+      "b.calendar.fromIcal: VCALENDAR has no VEVENT, VTODO or VJOURNAL components");
   }
   var converted = events.map(_veventToJsCalEvent)
-    .concat(todos.map(_vtodoToJsCalTask));
+    .concat(todos.map(_vtodoToJsCalTask))
+    .concat(journals.map(_vjournalToJsCalNote));
   return converted.length === 1 ? converted[0] : converted;
 }
 
@@ -276,7 +332,9 @@ function toIcal(jsCal, opts) {
   // maps to VEVENT. The wrapper + most properties are identical; the
   // wrapping component tag + Task-specific fields (DUE / STATUS /
   // PERCENT-COMPLETE / COMPLETED) diverge.
-  var component = jsCal["@type"] === "Task" ? "VTODO" : "VEVENT";
+  var component = jsCal["@type"] === "Task"
+    ? "VTODO"
+    : jsCal["@type"] === "Note" ? "VJOURNAL" : "VEVENT";
   var lines = [
     "BEGIN:VCALENDAR",
     "VERSION:2.0",
@@ -324,6 +382,11 @@ function toIcal(jsCal, opts) {
   if (component === "VTODO" && jsCal.progress) {
     lines.push("STATUS:" + String(jsCal.progress).toUpperCase());
   }
+  // RFC 5545 §3.8.1.11 — VJOURNAL STATUS values are DRAFT / FINAL /
+  // CANCELLED. JSCalendar Note carries them lower-cased; emit upper.
+  if (component === "VJOURNAL" && jsCal.status) {
+    lines.push("STATUS:" + String(jsCal.status).toUpperCase());
+  }
   if (component === "VTODO" && typeof jsCal.percentComplete === "number") {
     lines.push("PERCENT-COMPLETE:" + jsCal.percentComplete);
   }
@@ -449,11 +512,100 @@ function expandRecurrence(event, opts) {
       if (isFinite(mdn) && mdn !== 0 && mdn >= -31 && mdn <= 31) byMonthDaySet[mdn] = true;            // allow:raw-byte-literal — calendar day-of-month bounds
     }
   }
+  // RFC 5545 §3.3.10 — BYWEEKNO refines yearly recurrences to specific
+  // ISO 8601 week numbers (1..53 or -1..-53). Implementation
+  // computes the ISO week of each candidate instance + compares.
+  var byWeekNoSet = null;
+  if (Array.isArray(rule.byWeekNo) && rule.byWeekNo.length > 0) {
+    byWeekNoSet = Object.create(null);
+    for (var wni = 0; wni < rule.byWeekNo.length; wni += 1) {
+      var wn = parseInt(rule.byWeekNo[wni], 10);
+      if (isFinite(wn) && wn !== 0 && wn >= -53 && wn <= 53) byWeekNoSet[wn] = true;                   // allow:raw-byte-literal — ISO 8601 week-number bounds
+    }
+  }
+  // BYYEARDAY — day-of-year (1..366 or -1..-366; negative counts from
+  // the end of the year per RFC 5545 §3.3.10).
+  var byYearDaySet = null;
+  if (Array.isArray(rule.byYearDay) && rule.byYearDay.length > 0) {
+    byYearDaySet = Object.create(null);
+    for (var ydi = 0; ydi < rule.byYearDay.length; ydi += 1) {
+      var yd = parseInt(rule.byYearDay[ydi], 10);
+      if (isFinite(yd) && yd !== 0 && yd >= -366 && yd <= 366) byYearDaySet[yd] = true;                // allow:raw-byte-literal — day-of-year bounds
+    }
+  }
+  // BYHOUR / BYMINUTE / BYSECOND — time-of-day filters. RFC 5545 §3.3.10
+  // bounds: hours 0..23, minutes 0..59, seconds 0..60 (60 covers
+  // POSIX leap-second representation).
+  function _bySet(arr, lo, hi) {
+    if (!Array.isArray(arr) || arr.length === 0) return null;
+    var s = Object.create(null);
+    var hasAny = false;
+    for (var i = 0; i < arr.length; i += 1) {
+      var n = parseInt(arr[i], 10);
+      if (isFinite(n) && n >= lo && n <= hi) { s[n] = true; hasAny = true; }
+    }
+    // Codex P2 — when every value in the BY* list is out of range,
+    // return null instead of an empty set. An empty truthy set would
+    // cause `_matchesBy` to reject every candidate (`!set[n]` is
+    // true) and silently turn malformed input into a "match nothing"
+    // rule. Returning null lets the rule fall through to the next
+    // unfiltered candidate per RFC 5545's tolerant grammar.
+    return hasAny ? s : null;
+  }
+  var byHourSet   = _bySet(rule.byHour,   0, 23);                                                      // allow:raw-byte-literal — RFC 5545 hour range
+  var byMinuteSet = _bySet(rule.byMinute, 0, 59);                                                      // allow:raw-byte-literal — RFC 5545 minute range
+  var bySecondSet = _bySet(rule.bySecond, 0, 60);                                                      // allow:raw-byte-literal — RFC 5545 second range incl. leap second // allow:raw-time-literal — second-of-minute bound, not a duration
+
+  function _isoWeekParts(d) {
+    // ISO 8601 week-of-year + week-year. The week-YEAR can differ
+    // from the Gregorian year for early-Jan / late-Dec boundary
+    // dates (e.g. 2021-01-01 is ISO week 53 of WEEK-YEAR 2020).
+    // Returns { week, year }.
+    var tmp = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+    var dayOfWeek = tmp.getUTCDay() || 7;
+    tmp.setUTCDate(tmp.getUTCDate() + 4 - dayOfWeek);                                                  // allow:raw-byte-literal — ISO week-year anchor (Thursday)
+    var weekYear = tmp.getUTCFullYear();
+    var yearStart = new Date(Date.UTC(weekYear, 0, 1));
+    var week = Math.ceil((((tmp - yearStart) / 86400000) + 1) / 7);                                    // allow:raw-time-literal — 86400000 ms/day, 7 days/week // allow:raw-byte-literal
+    return { week: week, year: weekYear };
+  }
+  function _isoWeekOf(d) {
+    return _isoWeekParts(d).week;
+  }
+  function _yearDayOf(d) {
+    var startOfYear = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+    return Math.floor((d - startOfYear) / 86400000) + 1;                                               // allow:raw-time-literal — 86400000 ms/day // allow:raw-byte-literal
+  }
+  function _daysInYear(year) {
+    return ((year % 4 === 0 && year % 100 !== 0) || year % 400 === 0) ? 366 : 365;                      // allow:raw-byte-literal — Gregorian leap-year rule
+  }
   function _matchesBy(t) {
     var d = new Date(t);
     if (byDaySet && !byDaySet[d.getUTCDay()]) return false;
     if (byMonthSet && !byMonthSet[d.getUTCMonth() + 1]) return false;
     if (byMonthDaySet && !byMonthDaySet[d.getUTCDate()]) return false;
+    if (byWeekNoSet) {
+      // Codex P1 — ISO week-year vs Gregorian year. 2021-01-01 is ISO
+      // week 53 of WEEK-YEAR 2020 (since 2021 only has 52 ISO weeks).
+      // Comparing only the numeric week would let a Jan 1 2021 date
+      // match a BYWEEKNO=53 rule whose implicit year is 2021. Refuse
+      // when the candidate's ISO week-year doesn't match the
+      // candidate's Gregorian year (the most common operator-intent
+      // alignment); operators with boundary-crossing rules opt in via
+      // a future explicit knob if demand surfaces.
+      var iso = _isoWeekParts(d);
+      if (iso.year !== d.getUTCFullYear()) return false;
+      var lastWeek = _isoWeekOf(new Date(Date.UTC(d.getUTCFullYear(), 11, 28)));                       // allow:raw-byte-literal — Dec 28 always in last ISO week
+      if (!byWeekNoSet[iso.week] && !byWeekNoSet[-(lastWeek - iso.week + 1)]) return false;
+    }
+    if (byYearDaySet) {
+      var yd = _yearDayOf(d);
+      var dayCount = _daysInYear(d.getUTCFullYear());
+      if (!byYearDaySet[yd] && !byYearDaySet[-(dayCount - yd + 1)]) return false;
+    }
+    if (byHourSet   && !byHourSet[d.getUTCHours()])     return false;
+    if (byMinuteSet && !byMinuteSet[d.getUTCMinutes()]) return false;
+    if (bySecondSet && !bySecondSet[d.getUTCSeconds()]) return false;
     return true;
   }
   var t = startMs;
@@ -575,6 +727,72 @@ function _vtodoToJsCalTask(vt) {
   return jsCal;
 }
 
+// RFC 5545 §3.6.3 — VJOURNAL maps to a JSCalendar-shaped Note. The
+// VJOURNAL grammar permits MULTIPLE DESCRIPTION properties (the only
+// iCalendar component that does); blamejs joins them with a single
+// blank line to preserve operator-visible separators. STATUS is
+// limited to DRAFT / FINAL / CANCELLED (different from VTODO's
+// vocabulary), with no DUE / DURATION / PERCENT-COMPLETE / COMPLETED.
+function _vjournalToJsCalNote(vj) {
+  var props = (vj && vj.properties) || {};
+  var jsCal = {
+    "@type":  "Note",
+    uid:      _firstValue(props.UID) || "",
+    updated:  _icalDateTimeToUtc(_firstValue(props.DTSTAMP) || ""),
+  };
+  var summary = _firstValue(props.SUMMARY);
+  if (summary) jsCal.title = _unescapeText(summary);
+  // RFC 5545 §3.6.3 — VJOURNAL is the only component that may carry
+  // multiple DESCRIPTION properties (one per discrete journal entry).
+  // Concatenate them with a blank-line separator so downstream
+  // consumers see the operator-visible boundaries.
+  var descriptions = _allValues(props.DESCRIPTION);
+  if (descriptions.length === 1) {
+    jsCal.description = _unescapeText(descriptions[0]);
+  } else if (descriptions.length > 1) {
+    var parts = [];
+    for (var di = 0; di < descriptions.length; di += 1) {
+      parts.push(_unescapeText(descriptions[di]));
+    }
+    jsCal.description = parts.join("\n\n");
+  }
+  var dtstart = _firstValue(props.DTSTART);
+  if (dtstart) jsCal.start = _icalDateTimeToLocal(dtstart);
+  var tzid = _firstParamValue(props.DTSTART, "TZID");
+  if (tzid) {
+    jsCal.timeZone = tzid;
+  } else if (typeof dtstart === "string" && /Z$/.test(dtstart)) {
+    jsCal.timeZone = "Etc/UTC";
+  }
+  var status = _firstValue(props.STATUS);
+  if (status) {
+    var statusLower = String(status).toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(JSCAL_NOTE_STATUS, statusLower)) {
+      jsCal.status = statusLower;
+    }
+  }
+  var location = _firstValue(props.LOCATION);
+  if (location) {
+    jsCal.locations = { L1: { "@type": "Location", name: _unescapeText(location) } };
+  }
+  var rrule3 = _firstValue(props.RRULE);
+  if (rrule3) jsCal.recurrenceRules = [_icalRruleToJscal(rrule3)];
+  return jsCal;
+}
+
+function _allValues(prop) {
+  if (!prop) return [];
+  if (Array.isArray(prop)) {
+    var out = [];
+    for (var i = 0; i < prop.length; i += 1) {
+      var item = prop[i];
+      if (item && item.value !== undefined) out.push(item.value);
+    }
+    return out;
+  }
+  return prop.value !== undefined ? [prop.value] : [];
+}
+
 function _firstValue(prop) {
   if (!prop) return null;
   if (Array.isArray(prop)) {
@@ -720,6 +938,7 @@ module.exports = {
   JSCAL_FREQUENCIES:      JSCAL_FREQUENCIES,
   JSCAL_ALERT_ACTIONS:    JSCAL_ALERT_ACTIONS,
   JSCAL_TASK_PROGRESS:    JSCAL_TASK_PROGRESS,
+  JSCAL_NOTE_STATUS:      JSCAL_NOTE_STATUS,
   MAX_EXPAND_INSTANCES:   MAX_EXPAND_INSTANCES,
   MAX_EXPAND_SPAN_MS:     MAX_EXPAND_SPAN_MS,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.35",
+  "version": "0.11.37",
   "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:ce80c06c-78db-449e-871f-1b1da1e018c7",
+  "serialNumber": "urn:uuid:df42b2e1-b180-4b98-a9b7-2bf6b7fe666e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T20:42:06.128Z",
+    "timestamp": "2026-05-21T22:14:19.947Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.35",
+      "bom-ref": "@blamejs/core@0.11.37",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.35",
+      "version": "0.11.37",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.35",
+      "purl": "pkg:npm/%40blamejs/core@0.11.37",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.35",
+      "ref": "@blamejs/core@0.11.37",
       "dependsOn": []
     }
   ]