@blamejs/core 0.11.41 → 0.11.43

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.43 (2026-05-22) — **Wiki nav: alphabetical sidebar + dedup drifted category labels.** The wiki sidebar now lists categories alphabetically (case-insensitive) instead of in editorial order. Welcome remains pinned first (landing page); Other and Reference remain pinned last (catch-all groups). Three category-label dups are also consolidated at the source comment-blocks: `Agent Protocols` (one entry — `a2a-tasks`) joins `Agent` with the rest of the agent substrate; `Networking` (two entries — `stream-throttle`, `web-push-vapid`) joins `Network`; `Audit & Compliance` (one entry — `nist-crosswalk`) joins `Compliance`. New `@nav` categories now land in their alphabetical slot automatically without a site.config edit. **Changed:** *Wiki sidebar group order alphabetical* — Replaces the curated `GROUP_ORDER` editorial list in `examples/wiki/site.config.js` with an alphabetical sort. Pinning preserved: `Welcome` always first; `Other` and `Reference` always last. Adding a new `@nav` category to any `lib/*.js` `@module` block now slots into its alphabetical position automatically — no separate site.config update required. · *Category consolidation: Agent Protocols → Agent* — `a2a-tasks` was the sole entry under `Agent Protocols`. Moved to `Agent` to live alongside the orchestrator / saga / idempotency / event-bus / posture-chain / stream / trace / tenant / snapshot / fsm primitives — the W3C A2A task surface is part of the same agent-substrate concern. · *Category consolidation: Networking → Network* — `stream-throttle` and `web-push-vapid` were tagged `Networking` while every other network-layer primitive used `Network`. Drift cleanup — both now live under `Network`. · *Category consolidation: Audit & Compliance → Compliance* — `nist-crosswalk` was the sole entry under `Audit & Compliance`. Moved to `Compliance` alongside the other regulatory primitives. **Detectors:** *Nav-category allowlist gate* — `testNavCategoryAllowlist` in the codebase-patterns runner walks every `lib/*.js` `@module` block and refuses any `@nav` value not in the canonical category list. Adding a new sidebar category is a deliberate edit — it lands in `NAV_ALLOWLIST` + the operator-facing `FIRST_GROUPS` / `LAST_GROUPS` pin list in `examples/wiki/site.config.js` at the same time. Prevents the Networking-vs-Network and Agent-vs-Agent-Protocols dup classes from re-emerging silently.
+
+- 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)

package/lib/a2a-tasks.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * @module     b.a2a
- * @nav        Agent Protocols
+ * @nav        Agent
  * @title      A2A Tasks
  * @order      600
  *

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 /

package/lib/nist-crosswalk.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * @module     b.nistCrosswalk
- * @nav        Audit & Compliance
+ * @nav        Compliance
  * @title      NIST control crosswalk
  * @order      150
  * @slug       nist-crosswalk

package/lib/stream-throttle.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * @module     b.streamThrottle
- * @nav        Networking
+ * @nav        Network
  * @title      Stream Throttle
  * @order      130
  * @slug       stream-throttle

package/lib/web-push-vapid.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * @module b.webPush
- * @nav    Networking
+ * @nav    Network
  * @title  Web Push (VAPID)
  * @order  240
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.41",
+  "version": "0.11.43",
   "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:5557c11a-5977-46f0-8a4f-c25e3b621e70",
+  "serialNumber": "urn:uuid:a9f75389-959c-4392-b31b-fb5f89c46d4a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-22T01:26:53.795Z",
+    "timestamp": "2026-05-22T03:08:03.790Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.41",
+      "bom-ref": "@blamejs/core@0.11.43",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.41",
+      "version": "0.11.43",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.41",
+      "purl": "pkg:npm/%40blamejs/core@0.11.43",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.41",
+      "ref": "@blamejs/core@0.11.43",
       "dependsOn": []
     }
   ]