Integrate wave 7 (micropub, backup): 26 plugins, 264 tests + REPORT.md

compose.test.js and serve.js now boot all 26 from pure config (both new
plugins live under their own prefix — no appPaths widening needed).
Findings folded into NOTES.md: api.events gains its 5th consumer
(backup — incremental/scheduled backup unbuildable), api.serverInfo now
~12, the raw-body-stream seam (#583) gains micropub's media endpoint,
response-header injection gains micropub endpoint discovery, and
micropub is the reservePath counter-witness (client-discovered endpoints
fit the one-prefix model exactly).

New: REPORT.md — the maintainer-facing summary. What the api already
carries (26 plugins, eleven capability classes, zero core changes),
the four seams to add ranked by independent demand (authorize, events,
reservePath, serverInfo) each written as a fileable issue with
consumers/sketch/cost, two loader bug fixes, the #564 core/plugin line,
and a suggested order of work. NEXT.md updated: webhooks/webmention
deliberately deferred (outbound fetches to arbitrary URLs need a
focused, careful session).

Author: melvincarvalho

AGENT.md

@@ -11,7 +11,7 @@ Out-of-tree plugins for [JavaScript Solid
 Server](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer),
 built on its **#206 loader** (`createServer({ plugins })`, JSS ≥ 0.0.215).
 It is an *experiment*: prove the plugin api by using it, and treat every
-wall you hit as a finding, not a blocker. **20 plugins, ~200 tests today.**
+wall you hit as a finding, not a blocker. **26 plugins, 264 tests today.**
 
 ### The one rule that makes the experiment valid
 
@@ -149,6 +149,8 @@ Full ranking in `NOTES.md`. The ones you'll hit:
 | an object-storage / S3-style gateway | `s3/` | loopback LDP + hand-rolled XML + SigV4 |
 | a DID / identity document | `didweb/` | podsRoot scan + key derivation |
 | a dev/tooling subsystem | `gitscratch/` | shell a system binary via CGI |
+| a posting protocol (IndieWeb-style, client-discovered endpoint) | `micropub/` | pod bearer as the protocol token + loopback writes |
+| a data-export / archive download | `backup/` | loopback container walk streamed into a hand-rolled format |
 
 ## Footguns (every multi-boot suite rediscovered these)
 
@@ -166,7 +168,8 @@ Full ranking in `NOTES.md`. The ones you'll hit:
 
 ## Current state
 
-24 plugins (6 ports + 18 features), ~270 tests, all green (`npm test`).
+26 plugins (6 ports + 20 features), 264 tests, all green (`npm test`).
 `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.

ISSUES.md

@@ -35,6 +35,8 @@ evidence. Legend:
 | — | `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) |
+| — | `backup/` | pod → `.tar.gz` export (incremental backup → 🔩 `api.events`) |
 
 Plus six **ports of bundled features** proving the migration path for #564 /
 #164: `relay/` `webrtc/` `terminal/` `tunnel/` `notifications/`, and `pay/`
@@ -96,13 +98,13 @@ exists.
 ## Tally
 
 Of ~40 plugin-tagged issues: **13 built as plugins here** (plus `rss/`,
-`matrix/`, `search/`, `didweb/`, `s3/` — capability demonstrations with no
-single issue), **6 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. **24
-plugins total, ~270 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` (4 consumers — matrix
-`/sync` needs live push), `api.reservePath` (API-shims + didweb's
-parameterized case), and `api.serverInfo` (broadest: ~10 plugins hand-roll
-their own origin).
+`matrix/`, `search/`, `didweb/`, `s3/`, `micropub/`, `backup/` — capability
+demonstrations with no single issue), **6 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. **26 plugins total, 264 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` (5
+consumers — matrix `/sync` needs live push, backup can only pull-on-demand),
+`api.reservePath` (API-shims + didweb's parameterized case), and
+`api.serverInfo` (broadest: ~12 plugins hand-roll their own origin).

NEXT.md

@@ -8,16 +8,20 @@ plugin), `NOTES.md` (the findings/seams — the real deliverable), and
 
 ## Where things stand
 
-- **24 plugins, ~270 tests, all green** (`npm test`), all pushed to
+- **26 plugins, 264 tests, all green** (`npm test`), all pushed to
   `github.com/JavaScriptSolidServer/plugins` (branch `gh-pages`).
-- `compose.test.js` boots all 24 on **one** JSS from pure config; `serve.js`
+- `compose.test.js` boots all 26 on **one** JSS from pure config; `serve.js`
   is the runnable demo. Both must be updated when you add a plugin.
 - Built so far: 6 ports (relay, webrtc, terminal, tunnel, notifications,
-  pay) + 18 features (nip05, corsproxy, capability, webdav, sparql,
+  pay) + 20 features (nip05, corsproxy, capability, webdav, sparql,
   gitscratch, otp, carddav, mastodon, bluesky, caldav, webfinger,
-  activitypub, rss, matrix, search, didweb, s3).
+  activitypub, rss, matrix, search, didweb, s3, micropub, backup).
 - Capability classes covered: realtime, WebDAV family, fediverse/social/chat
-  (5 shims), identity, data/query/search, object storage, proxy, dev, pay.
+  (5 shims), IndieWeb publishing, identity, data/query/search, object
+  storage, proxy, dev, pay, data portability.
+- **REPORT.md exists** — the maintainer-facing summary (ranked seams, each
+  fileable nearly verbatim). Keep its consumer counts current as plugins
+  land.
 
 ## The hard rule (don't break it)
 
@@ -33,17 +37,18 @@ plugin), `NOTES.md` (the findings/seams — the real deliverable), and
    pinned to 0.0.215 on `gh-pages`. You may **read** it for reference; keep
    it clean.
 
-## Immediate next step: finish Wave 7
+## Wave 7 status
 
-Four plugins were *planned but not yet built* — this is where to resume:
+`micropub/` and `backup/` are **built and integrated**. Two remain
+*deliberately deferred*, not forgotten:
 
-| Plugin | What | Copy from |
+| Plugin | What | Why deferred |
 |---|---|---|
-| `webhooks/` | change-notification webhooks; **must poll** (no `api.events`) → the canonical 5th consumer of that seam, and a real integration primitive | notifications/ (fs.watch), rss/sparql (container walk) |
-| `micropub/` | IndieWeb Micropub server — POST creates a post in the pod | mastodon/ (auth + pod write via loopback) |
-| `webmention/` | IndieWeb Webmention receiver — store incoming mentions in the pod | activitypub/ inbox, capability/ |
-| `backup/` | pod container → `.tar.gz` download (data portability); hand-roll tar headers + `node:zlib` gzip (no deps) | webdav/rss (container walk) |
+| `webhooks/` | change-notification webhooks; **must poll** (no `api.events`) → a 6th consumer of that seam | POSTs to arbitrary operator-supplied URLs — build with corsproxy/-grade SSRF gates and a careful review, in a session focused on it |
+| `webmention/` | IndieWeb Webmention receiver — store incoming mentions in the pod | spec requires fetching the (arbitrary) source URL to verify the link — same outbound-fetch caution as webhooks |
 
+If you build them, copy notifications/ (fs.watch) + rss/sparql (walk) for
+webhooks, activitypub/ inbox + corsproxy/'s SSRF gates for webmention.
 Dispatch each as its own worker into its own directory (they don't conflict
 — separate subdirs, shared files touched only by you at integration time).
 Verify each with `node --test --test-concurrency=1 <name>/test.js`, then:
@@ -91,12 +96,15 @@ each. Current top four (keep this current as you add consumers):
 
 1. **`api.authorize(request, path, mode)`** — 3 consumers; the top
    *blocking* seam (authority the requester doesn't drive).
-2. **`api.events.onResourceChange`** — 4 consumers; matrix `/sync` needs
+2. **`api.events.onResourceChange`** — 5 consumers (backup/ made it 5:
+   incremental/scheduled backup is unbuildable); matrix `/sync` needs
    live push. Every "react to writes" plugin (webhooks, WebSub, indexing)
-   will want it — webhooks/ (wave 7) makes it 5.
+   will want it — webhooks/ would make it 6.
 3. **`api.reservePath`** — every API-shim owns fixed roots outside its one
    prefix and can't self-exempt; didweb needs a *parameterized* form.
-4. **`api.serverInfo`** — broadest (~10 plugins hand-roll their origin).
+   (micropub/ is the counter-witness: client-discovered endpoints need no
+   reservation — the seam is about protocol-fixed paths.)
+4. **`api.serverInfo`** — broadest (~12 plugins hand-roll their origin).
 
 Plus: the unconsumed-body-**stream** primitive (#583), `api.mcp.registerTool`
 (blocks the MCP-tool issues #495/#496/#500/#501), can't-set-server-options,
@@ -105,12 +113,12 @@ empirically in NOTES: **route-owning → plugin, pipeline-modifying → core**.
 
 ## Meta-work worth doing (beyond more plugins)
 
-- **A summary write-up** the maintainer can act on: "the plugin api reaches
-  N of ~40 tagged issues; here are the M seams to add next, ranked, each
-  with consumers." Half of this exists in `ISSUES.md`/`NOTES.md` already.
+- **The summary write-up is DONE — `REPORT.md`.** Keep it current (counts,
+  consumers) whenever a wave lands; it's written so each seam could be
+  filed nearly verbatim.
 - **Filing the seams as upstream issues** — but only if the maintainer asks
-  (core-repo interaction is currently off; see the hard rule). Draft them
-  here first if so.
+  (core-repo interaction is currently off; see the hard rule). REPORT.md
+  is the draft.
 
 ## Footguns (every multi-boot test suite rediscovered these)
 

NOTES.md

@@ -38,31 +38,38 @@ ports reached for it without coordinating.
    #382), or a capability exercising the *issuer's* authority
    (capability #506). This is the most-requested seam and the one that
    moves the most backlog issues from "plugin-approximation" to "faithful".
-2. **`api.events.onResourceChange(cb)`** — **four consumers now:
-   notifications/, sparql/, search/, matrix/**, in rising sharpness:
-   notifications (a miss is a *late* notification), sparql (a miss is a
-   *wrong* query result), search (a miss is *stale results*, the property
-   users most expect to be fresh — the most user-visible instance), and
-   matrix (its `/sync?since=` long-poll needs server-side sync cursors +
-   **live push on writes** — an event hook feeding `api.ws.route` — so a
-   stateless bridge can only do full-state `/sync` at all). Core already has
-   the emitter internally (`src/notifications/events.js`); this is the seam
+2. **`api.events.onResourceChange(cb)`** — **five consumers now:
+   notifications/, sparql/, search/, matrix/, backup/**, in rising
+   sharpness: notifications (a miss is a *late* notification), sparql (a
+   miss is a *wrong* query result), search (a miss is *stale results*, the
+   property users most expect to be fresh — the most user-visible
+   instance), matrix (its `/sync?since=` long-poll needs server-side sync
+   cursors + **live push on writes** — an event hook feeding `api.ws.route`
+   — so a stateless bridge can only do full-state `/sync` at all), and
+   backup (with no change hook *and* no plugin-owned read authority,
+   incremental and scheduled/server-initiated backup are both unbuildable —
+   every backup is a caller-driven full crawl). Core already has the
+   emitter internally (`src/notifications/events.js`); this is the seam
    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)** — **eight+
+3. **`api.serverInfo` (`{ baseUrl, port }` at listen)** — **a dozen+
    consumers: notifications/, webdav/, carddav/, caldav/, sparql/, rss/,
-   nip05/, webfinger/, mastodon/, bluesky/, activitypub/** — essentially
+   nip05/, webfinger/, mastodon/, bluesky/, activitypub/, micropub/,
+   backup/** — 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
    (vs. api.authorize being the most *blocking*); trivially cheap to provide.
-4. **The unconsumed-body-**stream** primitive (#583)** — consumer:
-   gitscratch/ sharpened it. tunnel/ needed the raw *buffer*; git needs the
-   raw *stream* piped to a subprocess gzip-and-all. Whatever `api.mountApp`
-   / raw-body mode ships must hand back the un-drained stream, not just a
-   buffered body. (This is exactly what the merged loader's scoped
-   pass-through parser does — the finding is to keep it that way.)
+4. **The unconsumed-body-**stream** primitive (#583)** — consumers:
+   gitscratch/ sharpened it; micropub/ adds a blocked one. tunnel/ needed
+   the raw *buffer*; git needs the raw *stream* piped to a subprocess
+   gzip-and-all; micropub's **media endpoint** (multipart file upload) is
+   simply not implemented until a plugin can pipe an un-drained body.
+   Whatever `api.mountApp` / raw-body mode ships must hand back the
+   un-drained stream, not just a buffered body. (This is exactly what the
+   merged loader's scoped pass-through parser does — the finding is to
+   keep it that way.)
 5. **Routes/WAC-exemption outside the single prefix** — **the most-hit
    finding: seven+ consumers.** A plugin can *register* absolute/exact
    routes outside its prefix (the loader doesn't confine `api.fastify`), but
@@ -98,7 +105,11 @@ ports reached for it without coordinating.
    (or `paths: [...]` in the entry) — the loader exempts *and* claims each
    deliberately and reports collisions. The seam **every API-shim plugin**
    structurally requires; third most-demanded after `api.authorize` and
-   `api.events`.
+   `api.events`. **Counter-witness that sharpens it:** micropub/ is a
+   protocol shim that needed *no* reservation at all, because Micropub
+   endpoints are client-discovered rather than protocol-fixed — the seam
+   is specifically about protocols that pin absolute paths, not API shims
+   per se.
 6. **Can't set fastify server options** — consumer: capability/ hit
    `maxParamLength` (100) silently 404ing long tokens in named params;
    workaround is a wildcard route. A plugin has no way to raise per-route
@@ -107,10 +118,13 @@ ports reached for it without coordinating.
    (`src/nostr/event.js` NIP-01 verify), pay/ (`src/mrc20.js`). Pure crypto.
    Export like auth.js (`javascript-solid-server/nostr.js`) or bless
    vendoring.
-8. **Response-header injection on core routes** — consumer: notifications/
-   (`Updates-Via` discovery). A plugin can't add headers to routes it
-   doesn't own. NOT a default-on hook (bigger grant than route ownership);
-   gate behind `capabilities: ['hooks']` if ever.
+8. **Response-header injection on core routes** — **two consumers:
+   notifications/** (`Updates-Via` discovery) and **micropub/** (clients
+   find the endpoint via `<link rel="micropub">` on the user's homepage —
+   a core-owned resource the plugin can't decorate; the operator must
+   advertise it by hand). A plugin can't add headers to routes it doesn't
+   own. NOT a default-on hook (bigger grant than route ownership); gate
+   behind `capabilities: ['hooks']` if ever.
 
 ## Test-harness footguns (host quirks, not plugin api)
 
@@ -192,3 +206,14 @@ this repo is its proof.
 - Test harness dance: a plugin whose config references the server's own
   origin forces the port-probe-then-boot pattern (helpers.js `port` option)
   — same finding as api.serverInfo, visible in test setup.
+- **No snapshot semantics** (backup/): a multi-resource read is never
+  atomic — the api offers no lock, snapshot, or conditional multi-read, so
+  an archive of a busy pod is an honest but mixed-state export. Related:
+  a streaming response can't report post-walk results (skip counts) in
+  headers — they're committed before the walk starts and there are no
+  usable trailers — so backup/ writes an in-band `MANIFEST.json` as the
+  last archive entry.
+- **Permissions don't round-trip** (backup/): `.acl`/`.meta` could be
+  exported (loopback enforces Control for free) but absolute-URL ACLs
+  don't restore elsewhere — policy portability is a spec-level gap, not a
+  plugin-api gap.

README.md

@@ -82,12 +82,15 @@ README and NOTES.md, ship the closest honest approximation.
 | `search/` | — | full-text search over pod resources (TF-IDF) |
 | `didweb/` | — | `did:web` DID-document resolver for pods |
 | `s3/` | — | S3-compatible object-storage gateway (SigV4) |
+| `micropub/` | — | IndieWeb Micropub endpoint — posts land in the author's pod |
+| `backup/` | — | pod container → `.tar.gz` download (data portability) |
 
-**~270 tests, all green** (`npm test`), including `compose.test.js` — all
-twenty-four plugins on one server from pure config, pods + WAC intact
+**264 tests, all green** (`npm test`), including `compose.test.js` — all
+twenty-six plugins on one server from pure config, pods + WAC intact
 beside them. Findings consolidated in [NOTES.md](./NOTES.md); the full
 plugin-tagged backlog triaged in [ISSUES.md](./ISSUES.md); the build guide
-is [AGENT.md](./AGENT.md).
+is [AGENT.md](./AGENT.md); the maintainer-facing summary — what to add
+to the api next, ranked, with evidence — is [REPORT.md](./REPORT.md).
 
 ```
 <name>/plugin.js   the port          <name>/test.js   real-JSS tests   <name>/README.md   findings