integrate the 0.0.219 wave: gallery + federation-demo; docs true-up

compose/serve: gallery added (zero config — the point), the appPaths
array and its comment deleted (all four shims self-reserve now), stale
explicit-id comments replaced, gallery liveness probe added.

Docs: 34 plugins / 407 tests; ISSUES' shipped-upstream table gains
#601/#602/#583/#610/#596 (all consumed here); the reservePath and
serverInfo entries in NOTES/REPORT/NEXT flip from 'missing seam' to
'landed & consumed', keeping the history and recording what consumption
surfaced (bodyLimit sidestep in the mounted lane, matcher vs
maxParamLength, the JRD-registry ask, streaming ends at core's front
door); api.events is now the top open ask, then api.authorize.

Author: melvincarvalho

AGENT.md

@@ -80,19 +80,31 @@ Full ranking in `NOTES.md`. The ones you'll hit:
   Workaround: loopback with the requester's own creds covers the common
   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.** (4 shim
-  consumers.)
+- **`api.reservePath()` — LANDED (JSS 0.0.219, #602) and consumed.** A
+  plugin now claims + WAC-exempts its protocol-pinned paths itself:
+  literal roots (`api.reservePath('/xrpc', { methods: [...] })` — see
+  mastodon/bluesky/activitypub/matrix) and parameterized shapes
+  (`api.reservePath('/:user/did.json')` — see didweb/). Reservations are
+  READ-ONLY by default; widen `methods` to exactly the verbs your routes
+  implement, never wider (an exempted verb with no route falls through to
+  LDP's write wildcards unauthenticated). No more operator `appPaths`.
+  `/.well-known/*` still also rides core's blanket exemption; reserving a
+  well-known doc makes the claim deliberate and collision-guarded.
 - **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. ~23 plugins do this.
+- **`api.serverInfo` — LANDED (JSS 0.0.218, #601), retrofit in progress.**
+  Resolve the origin at REQUEST time (`api.serverInfo().baseUrl`; with an
+  ephemeral port it only exists once listening), keep `config.baseUrl` as
+  an optional reverse-proxy override. Consumed by webfinger/, didweb/,
+  dashboard/, admin/, gallery/; ~18 plugins still carry the old
+  config-pair pattern and retrofit the same way.
+- **`api.mountApp` — LANDED (JSS 0.0.219, #583).** A raw `(req,res)`
+  handler with the UN-drained request stream — the streaming-upload lane
+  Fastify's parsers can't give you. See gallery/ (the first consumer) for
+  the contract's edges: the mounted lane sidesteps the host `bodyLimit`
+  (cap your own if you don't forward to core), the two lanes can't share
+  a prefix, and `getAgent` needs a shim for raw reqs.
 - **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
@@ -140,7 +152,7 @@ Full ranking in `NOTES.md`. The ones you'll hit:
 |---|---|---|
 | a realtime/WebSocket service | `relay/` or `webrtc/` | `ws.route` + `pluginDir` |
 | a DAV-family protocol (CalDAV done, e.g. a filesystem/WebDAV variant) | `webdav/`→`carddav/`→`caldav/` | loopback + multistatus XML + ETag + Basic→Bearer, proven 3× |
-| an API shim (a new social/chat/proto) | `mastodon/` or `bluesky/` | token bridge + fixed-root `appPaths` |
+| an API shim (a new social/chat/proto) | `mastodon/` or `bluesky/` | token bridge + self-reserved fixed roots (#602) |
 | a `.well-known` discovery doc | `nip05/` or `webfinger/` | podsRoot scan + guarded absolute route |
 | a scoped-token / auth service | `capability/` or `otp/` | HMAC macaroon-lite + `pluginDir` |
 | a query/read/search over pod data | `sparql/`, `rss/`, `search/` | loopback container walk + forwarded auth |
@@ -158,6 +170,8 @@ Full ranking in `NOTES.md`. The ones you'll hit:
 | a storage protocol with conditional writes | `remotestorage/` | If-Match/If-None-Match pass through loopback intact |
 | a redirect / metadata micro-service | `shortlink/` | pluginDir JSON table + wildcard slug routes |
 | an operator/admin surface | `admin/` | compose probes + podsRoot scan behind an agent allowlist |
+| a streaming-body app (upload, media) | `gallery/` | `api.mountApp` raw handler → loopback PUT, auth forwarded |
+| a multi-server scenario (not a plugin) | `federation-demo/` | child-process instances (DATA_ROOT is process-global) |
 
 ## Footguns (every multi-boot suite rediscovered these)
 
@@ -167,9 +181,11 @@ Full ranking in `NOTES.md`. The ones you'll hit:
 - **Ambient `~/.gitconfig`** (git-shelling plugins): spawn git with
   `GIT_CONFIG_NOSYSTEM=1` and no `HOME`, or the operator's `init.defaultBranch`
   leaks into created repos.
-- **Generic basename id**: the loader derives the id from the module
-  basename; `<name>/plugin.js` all reduce to `plugin` and collide — always
-  pass an explicit `id` in `compose.test.js`/`serve.js`.
+- **Generic basename id — FIXED in JSS 0.0.219 (#596)**: the loader now
+  derives `<name>/plugin.js` → id `<name>` from the parent dir; explicit
+  `id` fields are gone from `compose.test.js`/`serve.js`. Don't reintroduce
+  them — but if a test hardcodes a pluginDir path, it's `.plugins/<name>/`
+  now, not `.plugins/plugin/`.
 - **Dotted prefixes** (`/.foo`) fail the WS upgrade — core reserves dotted
   paths. Use a plain prefix for anything with a socket.
 - **`logger: false` kills plugin `onResponse` hooks**: core's access-log
@@ -179,10 +195,14 @@ Full ranking in `NOTES.md`. The ones you'll hit:
 
 ## Current state
 
-33 plugins (7 ports + 26 features), 386 tests, all green (`npm test`).
+34 plugins (7 ports + 27 features) + the two-server `federation-demo/`,
+407 tests, all green (`npm test`).
 A four-axis security review ([SECURITY.md](./SECURITY.md)) hardened the
 inbound-federation and query surfaces; the WAC-deferral pattern held.
-`compose.test.js` runs every one on a single server from pure config. Two
-core PRs (#590 `api.mountApp`, #591 `/idp/refresh`) sit upstream, unmerged,
-for the maintainer's call. Everything else lives here, by design.
-[REPORT.md](./REPORT.md) is the maintainer-facing summary of it all.
+`compose.test.js` runs every plugin on a single server from pure config.
+Four seams have now LANDED upstream and are consumed here: `api.serverInfo`
+(#601), `api.reservePath` (#602), `api.mountApp` (#583), `api.plugins`
+(#610) — all in JSS 0.0.218/0.0.219, which this repo pins. Still open:
+`api.events` (#603) and `api.authorize` (#604). Everything else lives
+here, by design. [REPORT.md](./REPORT.md) is the maintainer-facing
+summary of it all.

ISSUES.md

@@ -23,27 +23,28 @@ evidence. Legend:
 | #507 | `webdav/` | mount a pod in Finder/Nautilus/Windows |
 | #509 | `sparql/` | SPARQL SELECT + UPDATE over pod JSON-LD (write-index → 🔩 `api.events`) |
 | #322 | `gitscratch/` | ephemeral Solid-authed git remotes (git-http-backend CGI) |
-| #515 / #516 | `mastodon/` | Mastodon-API shim — a client can log into its own pod (needs `appPaths` widened → 🔩) |
+| #515 / #516 | `mastodon/` | Mastodon-API shim — a client can log into its own pod (self-reserves `/api`+`/oauth` — #602 consumed) |
 | #505 | `otp/` | one-time-password session flow (account *recovery* → 🔩 core auth) |
 | #157 | `carddav/` | CardDAV contact sync (iOS/macOS/Thunderbird/DAVx5) |
-| #211 | `bluesky/` | AT-Protocol XRPC shim — a client logs into its own pod (needs `appPaths` widened → 🔩) |
+| #211 | `bluesky/` | AT-Protocol XRPC shim — a client logs into its own pod (self-reserves `/xrpc` — #602 consumed) |
 | #157-sib | `caldav/` | CalDAV calendar sync — completes the DAV family |
 | #164 | `webfinger/` | `/.well-known/webfinger` — the WebFinger half of #164 |
-| #51/#164 | `activitypub/` | federate a pod as an AS2 actor (needs `appPaths` widened → 🔩) |
+| #51/#164 | `activitypub/` | federate a pod as an AS2 actor (self-reserves `/ap` — #602 consumed) |
 | — | `rss/` | any pod container as an Atom/RSS feed |
 | — | `matrix/` | Matrix Client-Server API shim (chat) |
 | — | `search/` | full-text search over pod resources |
 | — | `didweb/` | `did:web` DID-document resolver |
 | — | `s3/` | S3-compatible object-storage gateway |
-| — | `micropub/` | IndieWeb Micropub endpoint (media upload → 🔩 raw-body stream #583) |
+| — | `micropub/` | IndieWeb Micropub endpoint (media upload: #583 landed as api.mountApp — parser work remains, see gallery/) |
 | — | `backup/` | pod → `.tar.gz` export (incremental backup → 🔩 `api.events`) |
 | — | `metrics/` | `/healthz` + Prometheus exporter (core-pipeline metrics → 🔩 gated hooks) |
-| — | `dashboard/` | plugin status page (sibling discovery → 🔩 app-registry #463/#464) |
+| — | `dashboard/` | plugin status page (sibling discovery via api.plugins #610 — consumed) |
 | — | `oembed/` | oEmbed provider (discovery injection → 🔩 header/content hooks) |
-| — | `jmap/` | JMAP mail over the pod (push/delta → 🔩 `api.events`; blobs → 🔩 #583) |
+| — | `jmap/` | JMAP mail over the pod (push/delta → 🔩 `api.events`; blobs: #583 landed as api.mountApp — retrofit pending) |
 | #163 | `remotestorage/` | remoteStorage server — 7th port; witnessed the webfinger collision |
 | — | `shortlink/` | link shortener for pod URLs (pluginDir persistence, 11th witness) |
 | #463/#464-adj | `admin/` | operator home — the wp-admin gap analysis; every missing pillar names a seam |
+| #583-adj | `gallery/` | pod photo/media gallery — first `api.mountApp` consumer; zero required config |
 
 Plus seven **ports of bundled features** proving the migration path for
 #564 / #164: `relay/` `webrtc/` `terminal/` `tunnel/` `notifications/`
@@ -58,6 +59,11 @@ Plus seven **ports of bundled features** proving the migration path for
 | #582 | `appPaths` WAC exemption, v0.0.213 |
 | #584 | `api.auth.getAgent`, v0.0.214 |
 | #588 | `api.ws.route` WebSocket routing, v0.0.215 |
+| #601 | `api.serverInfo` — the server's own origin, v0.0.218; consumed by webfinger/didweb/dashboard/admin/gallery |
+| #602 | `api.reservePath` — literal + parameterized, v0.0.218; consumed by the four shims + didweb |
+| #583 | `api.mountApp` — raw handler, un-drained stream, v0.0.218; consumed by gallery/ |
+| #610 | `api.plugins` — the loaded-plugin roster, v0.0.218; consumed by dashboard/ + admin/ |
+| #596 | generic-basename id derivation fix, v0.0.219 — the explicit-id workaround deleted repo-wide |
 | #564 | the core/plugin line — answered empirically in [NOTES.md](./NOTES.md) |
 
 ## Plugin-able, not yet built 🧩
@@ -76,10 +82,9 @@ Each names the seam and the consumer that proves it. Ranked in
 |---|---|
 | #509 (write-index), #501 | `api.events.onResourceChange` — react to pod writes |
 | #382 (per-pod ACL), #506 (pod grants) | `api.authorize(request, path, mode)` — ask the host's WAC |
-| #515/#516, #211 (both built, but need operator `appPaths`) | `api.reservePath()` — an API-shim owns fixed roots outside its prefix and can't self-exempt them from WAC; **two independent confirmations** |
 | #505 (recovery) | `api.auth.mintSession` / `api.identity.addAuthKey` — turn a proven channel into pod authority |
 | #495 #496 #500 #501 | `api.mcp.registerTool` — MCP has no plugin-tool seam; all four MCP issues want new tools a plugin can't add today |
-| #463 #464 | app-registry primitive — surfacing installed plugins as Solid resources; `dashboard/` is the live proof-of-need (it must be handed a hand-copied duplicate of the `createServer` list) |
+| #463 #464 | app-registry primitive — surfacing installed plugins as *Solid resources*; the in-process half landed as `api.plugins` (#610, consumed by dashboard/+admin/), the as-pod-resources half is still open |
 
 ## Core, not a plugin 🏛️ (a finding, not a gap)
 
@@ -107,15 +112,18 @@ exists.
 
 Of ~40 plugin-tagged issues: **14 built as plugins here** (plus `rss/`,
 `matrix/`, `search/`, `didweb/`, `s3/`, `micropub/`, `backup/`, `metrics/`,
-`dashboard/`, `oembed/`, `jmap/`, `shortlink/`, `admin/` — capability
-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, 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` (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: ~23 plugins hand-roll their own origin).
+`dashboard/`, `oembed/`, `jmap/`, `shortlink/`, `admin/`, `gallery/` —
+capability demonstrations with no single issue), **7 ported**, **10
+shipped upstream** (the loader plus four seams and the id fix in JSS
+0.0.218/0.0.219, each consumed here), **2 more plugin-able with no
+blocker**, **4 clusters blocked on a named seam** (each with a
+proof-of-need consumer), the rest core-by-nature or product-scale.
+**34 plugins total, 407 tests** (plus the two-server `federation-demo/`
+scenario). The plugin api reaches most of the backlog today; ranked by
+demand, the seams that would unlock the most next are `api.authorize`
+(4 consumers, 3 hard-blocked) and `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` and `api.serverInfo` — the
+former #3 and #4 — are **landed and consumed**; what remains of them is
+the JRD/link registry for shared discovery documents and the ~18
+mechanical serverInfo retrofits.