docs: true-up the seam consumer counts and the stale test tally

- 374 -> 386 tests everywhere the old number survived (ISSUES, NEXT,
  STRATEGY; README/AGENT/SECURITY already said 386).
- api.serverInfo: the honest count is 23 consumers (grep-verified
  config.baseUrl/loopbackUrl readers), not ~16/~10 — the list gains
  matrix, metrics, s3, search, shortlink, didweb, admin and drops nip05,
  whose own README finding says NIP-05 docs carry no absolute self-URLs
  (its repetition is the podsRoot/data-root class, which serverInfo does
  not cover). Stage-3 first-retrofit picks are now webfinger + didweb,
  the two whose wrong-origin failure is silent.
- api.authorize: one set of four consumers everywhere (corsproxy,
  capability, pay, caldav) — NOTES had counted notifications, which its
  own next sentence says the loopback trick covers.
- api.reservePath: four protocol-shim confirmations, not three — matrix's
  /_matrix root is witnessed in matrix/test.js and was already counted in
  REPORT.
- Footguns: fs.watch needs a free inotify instance; at the
  max_user_instances cap the three notifications tests time out (EMFILE)
  — an environment failure, not a regression.

Author: melvincarvalho

AGENT.md

@@ -78,21 +78,21 @@ Full ranking in `NOTES.md`. The ones you'll hit:
   allow this?" for authority the *requester* doesn't drive (a proxy governed
   by a pod owner's `.acl`, a capability exercising the *issuer's* right).
   Workaround: loopback with the requester's own creds covers the common
-  case; the issuer-authority case has no workaround — document it. (3
+  case; the issuer-authority case has no workaround — document it. (4
   consumers; the top blocking seam.)
 - **No `api.reservePath()`** — you can register routes outside your one
   `prefix`, but only `prefix` is WAC-exempt. `/.well-known/*` works by luck
   (core blanket-exempts it). Fixed roots like `/api`, `/xrpc`, `/ap` do
   **not** work until the operator passes `appPaths: ['/api',...]` to
   `createServer`. **If you build an API shim, your `test.js` must pass those
-  `appPaths`, and your README must say the operator does too.** (3 shim
+  `appPaths`, and your README must say the operator does too.** (4 shim
   consumers.)
 - **No `api.events.onResourceChange`** — you can't react to pod writes, so a
   write-time index / cached feed is impossible; do read-time work (walk the
   container per request) and note the O(N) cost. See `sparql/`, `rss/`.
 - **No `api.serverInfo`** — a plugin can't learn its own origin at
   `activate` time. Take `config.baseUrl` (and `loopbackUrl`), and `throw` if
-  missing. ~10 plugins do this.
+  missing. ~23 plugins do this.
 - **No `api.mcp.registerTool`** — MCP tools can't be added by a plugin
   (that's why #495/#496/#500/#501 aren't here).
 - **Can't set Fastify server options** — e.g. `maxParamLength` (100) 404s

ISSUES.md

@@ -111,11 +111,11 @@ Of ~40 plugin-tagged issues: **14 built as plugins here** (plus `rss/`,
 demonstrations with no single issue), **7 ported**, **5 shipped upstream**,
 **2 more plugin-able with no blocker**, **6 clusters blocked on a named
 seam** (each with a proof-of-need consumer), the rest core-by-nature or
-product-scale. **33 plugins total, 374 tests.** The plugin api reaches most
+product-scale. **33 plugins total, 386 tests.** The plugin api reaches most
 of the backlog today; ranked by demand, the seams that would unlock the
-most next are `api.authorize` (3 blocking consumers), `api.events` (7
+most next are `api.authorize` (4 consumers, 3 hard-blocked), `api.events` (7
 consumers — matrix `/sync` needs live push, jmap can't do push or delta
 sync, backup can only pull-on-demand),
 `api.reservePath` (API-shims + didweb's parameterized case + the
 **witnessed** webfinger collision), and
-`api.serverInfo` (broadest: ~16 plugins hand-roll their own origin).
+`api.serverInfo` (broadest: ~23 plugins hand-roll their own origin).

NEXT.md

@@ -8,7 +8,9 @@ plugin), `NOTES.md` (the findings/seams — the real deliverable), and
 
 ## Where things stand
 
-- **33 plugins, 374 tests, all green** (`npm test`), all pushed to
+- **33 plugins, 386 tests, all green** (`npm test`; the three
+  `notifications/` fs.watch tests need a free inotify instance — see
+  Footguns), all pushed to
   `github.com/JavaScriptSolidServer/plugins` (branch `gh-pages`).
 - `compose.test.js` boots all 33 on **one** JSS from pure config; `serve.js`
   is the runnable demo — its front door is now `admin/` (`/admin/`), the
@@ -93,9 +95,14 @@ rather than deleting it everywhere.
 
 ### Recommended first move
 
-Don't retrofit all ~16 at once. Do **`nip05/` + `webfinger/`** first — the
-two where a wrong origin fails *silently* (nip05 serves an empty identity
-map), so the before/after story is strongest. One plugins-repo PR against
+Don't retrofit all ~23 at once. Do **`webfinger/` + `didweb/`** first — the
+two where a wrong origin fails *silently* (webfinger mints WebIDs/JRD links
+on the wrong origin; didweb serves a `did.json` whose `id` doesn't match
+the URL it's fetched from), so the before/after story is strongest. (An
+earlier draft named nip05/ here — wrongly: its own README finding says
+NIP-05 documents contain no absolute self-URLs, so it needs no `baseUrl`;
+its silent-empty-map failure is the *data-root* repetition class,
+`config.podsRoot`, which `serverInfo` does not cover.) One plugins-repo PR against
 a locally-linked core, proving the loop closes; once core publishes, flip
 the pin and merge. The rest follow the same shape. Then the next seam:
 `reservePath` (#602) → `events` (#603) → `authorize` (#604).
@@ -174,8 +181,8 @@ it sharpens the case.
 `NOTES.md` ranks candidate seams by how many independent plugins demanded
 each. Current top four (keep this current as you add consumers):
 
-1. **`api.authorize(request, path, mode)`** — 4 consumers (caldav
-   scheduling joined); the top
+1. **`api.authorize(request, path, mode)`** — 4 consumers (corsproxy,
+   capability, pay, caldav — caldav scheduling joined); the top
    *blocking* seam (authority the requester doesn't drive).
 2. **`api.events.onResourceChange`** — 7 consumers (backup, jmap,
    remotestorage joined); matrix `/sync` needs
@@ -186,7 +193,7 @@ each. Current top four (keep this current as you add consumers):
    prefix and can't self-exempt; didweb needs a *parameterized* form.
    (micropub/ is the counter-witness: client-discovered endpoints need no
    reservation — the seam is about protocol-fixed paths.)
-4. **`api.serverInfo`** — broadest (~16 plugins hand-roll their origin).
+4. **`api.serverInfo`** — broadest (~23 plugins hand-roll their origin).
    **FILED #601, MERGED as core #605** — see the Stage-3 plan above for
    consuming it. reservePath #602, events #603, authorize #604 still open.
 
@@ -216,6 +223,11 @@ empirically in NOTES: **route-owning → plugin, pipeline-modifying → core**.
 - Dotted prefixes (`/.foo`) fail the WS upgrade — use plain prefixes for
   anything with a socket. (`/.well-known/*` HTTP works, by core's blanket
   exemption — but that's the reserved-path finding, not a guarantee.)
+- `fs.watch` needs a free inotify instance: when the machine is at
+  `fs.inotify.max_user_instances`, watch creation fails (EMFILE) and the
+  three `notifications/` fan-out tests time out. An environment failure,
+  not a regression — check `sysctl fs.inotify.max_user_instances` before
+  debugging the plugin.
 
 ## Issue tracker (new — 2026-07)
 
@@ -237,6 +249,6 @@ narrative, issues are the actionable subset.
   #596–#600, four seams as core **#601 (serverInfo), #602 (reservePath),
   #603 (events), #604 (authorize)**. Next upstream step (Stage 3, needs
   the core-freeze lifted): ship `serverInfo` (#601) end-to-end as the
-  reference PR — cheapest seam, ~16 consumers — then retrofit the plugins
+  reference PR — cheapest seam, ~23 consumers — then retrofit the plugins
   that hand-roll their origin. Secondary asks (api.plugins, api.isOperator)
   not filed yet; raise when a design discussion on the four opens.

NOTES.md

@@ -38,13 +38,14 @@ Twelve plugins in, the ranking is now empirical — a seam's rank is how many
 ports reached for it without coordinating.
 
 1. **`api.authorize(request, path, mode)`** — "would the host's WAC allow
-   this?" **Four independent consumers: notifications/, corsproxy/,
-   capability/, caldav/.** The loopback trick (below) covers the case where
+   this?" **Four independent consumers: corsproxy/, capability/, pay/,
+   caldav/.** The loopback trick (below) covers the case where
    the *requester's own* credentials should decide (notifications, webdav,
    sparql all use it), but it can't cover authorization the requester
    doesn't drive: a proxy governed by a *pod owner's* `.acl` (corsproxy
    #382), a capability exercising the *issuer's* authority
-   (capability #506), or CalDAV scheduling (RFC 6638), where Outbox→Inbox
+   (capability #506), pay/'s 402 gate (which wants to *compose with* WAC
+   rather than replace it), or CalDAV scheduling (RFC 6638), where Outbox→Inbox
    delivery is a write into the *recipient's* pod the sender has no WAC
    right to make — loopback structurally cannot express it (a
    server-mediated deliver-to-inbox primitive is the narrower
@@ -78,13 +79,18 @@ ports reached for it without coordinating.
    every "react to pod writes" app (webhooks, indexing, sync, search, live
    chat) will want, and it's now clearly the #2 most-demanded after
    `api.authorize`.
-3. **`api.serverInfo` (`{ baseUrl, port }` at listen)** — **a dozen+
+3. **`api.serverInfo` (`{ baseUrl, port }` at listen)** — **23
    consumers: notifications/, webdav/, carddav/, caldav/, sparql/, rss/,
-   nip05/, webfinger/, mastodon/, bluesky/, activitypub/, micropub/,
-   backup/, dashboard/, oembed/, jmap/, remotestorage/** — essentially
+   webfinger/, mastodon/, bluesky/, activitypub/, matrix/, micropub/,
+   backup/, metrics/, dashboard/, oembed/, jmap/, remotestorage/, s3/,
+   search/, shortlink/, didweb/, admin/** — essentially
    every plugin that mints absolute URLs or reaches the host over loopback.
-   All repeat the origin in config today; a wrong value fails quietly (nip05
-   serves an empty identity map). The single most *broadly* needed seam
+   All repeat the origin in config today; a wrong value fails quietly
+   (webfinger mints WebIDs on the wrong origin; didweb serves a `did.json`
+   whose `id` doesn't match its URL). (nip05/ was once listed here —
+   wrongly: its README finding is that NIP-05 documents carry no absolute
+   self-URLs; its config repetition is the *data-root* class, `podsRoot`,
+   which serverInfo doesn't cover.) The single most *broadly* needed seam
    (vs. api.authorize being the most *blocking*); trivially cheap to provide.
 4. **The unconsumed-body-**stream** primitive (#583)** — consumers:
    gitscratch/ sharpened it; micropub/ adds a blocked one. tunnel/ needed
@@ -109,9 +115,10 @@ ports reached for it without coordinating.
      most-wanted `.well-known` docs a deployment serves**, both riding the
      same undocumented luck.
    - **fixed roots core does NOT exempt** — mastodon/ (`/api`,`/oauth`),
-     bluesky/ (`/xrpc`), activitypub/ (`/ap`). Here the plugin **cannot
+     bluesky/ (`/xrpc`), activitypub/ (`/ap`), matrix/ (`/_matrix`). Here
+     the plugin **cannot
      serve its own surface**: every call 401s at the WAC hook until the
-     operator hand-passes `appPaths`. **Three independent protocol-shim
+     operator hand-passes `appPaths`. **Four independent protocol-shim
      confirmations**, each built separately. bluesky sharpened it (one root,
      still unreachable → the ask is "declare owned paths," not "more
      prefixes"); activitypub sharpened it further — its natural layout wants

REPORT.md

@@ -176,11 +176,13 @@ exists, moving it from operator config to plugin declaration.
 
 ### 4. `api.serverInfo` — the broadest, and the cheapest (#601)
 
-**~16 consumers** — every plugin that mints absolute URLs or loopbacks
-(the DAV family, the shims, rss, sparql, nip05, webfinger, notifications,
-micropub, backup, metrics, dashboard, oembed, jmap, remotestorage…)
+**23 consumers** — every plugin that mints absolute URLs or loopbacks
+(the DAV family, the four shims, rss, sparql, webfinger, notifications,
+micropub, backup, metrics, dashboard, oembed, jmap, remotestorage, s3,
+search, shortlink, didweb, admin)
 repeats `baseUrl`/`loopbackUrl` in config today. A wrong value fails
-*quietly* (nip05 serves an empty map). Test suites all need a
+*quietly* (webfinger mints WebIDs on the wrong origin; didweb serves a
+`did.json` whose `id` doesn't match its URL). Test suites all need a
 probe-port-then-boot dance for the same reason.
 
 **Sketch:** `{ baseUrl, port }` available by `activate`-time or via an
@@ -335,7 +337,7 @@ hooks capability.
 
 If effort is scarce, this order maximizes unblocked value per unit cost:
 
-1. `api.serverInfo` (trivial; tidies ~16 plugins' config and every test
+1. `api.serverInfo` (trivial; tidies ~23 plugins' config and every test
    harness),
 2. `api.reservePath` (small-medium; makes four existing shims
    self-contained and didweb *possible* — pair it with a webfinger link

STRATEGY.md

@@ -3,7 +3,7 @@
 Companion to [REPORT.md](./REPORT.md) (what to build into the api next).
 This file answers the other question: **where does a JSS + plugins stack
 sit in the ecosystem, what's missing, and what's the realistic play?**
-Written 2026-07, at 33 plugins / 374 tests.
+Written 2026-07, at 33 plugins / 386 tests.
 
 ## The one-line position