Design: durable afterCommit for user-installed plugins (#1851)

[michielbdejong]

Refs #1851

Design only, no code: planning/durable-after-commit.md. Step 4 of planning/plugin-runtime-convergence.md now points to it, and the planning index lists it.

Summary

• What it is. The hook is a queued, at-least-once notification. It is not an inline class extender, so it never blocks or fails a commit. The WASI after_commit stays for operator-installed server extensions. onResourceGet and beforeCommit are not widened.
• Scope. Defined in data terms: a View under the table, listed in table-views, whose view-kind names an app. The app must resolve to an active JS extension-world installation that declares entrypoints.afterCommit. A server-recorded subscription must also exist, made by the same signed gestures as the Let an app shown as a table's view edit its rows through a grant (#1740) #1788 grant. A live row grant is not required; it only decides whether writes apply or wait for review.
• Durability. A wake-up marker is upserted in the same transaction as Per-table change list with tombstones (#1850) #1885's change-log entry, so it covers commits, sync, import and removals. It rides the existing plugin-event/v1/ queue, drain worker and journal. The host keeps an opaque cursor per (installation, table), hands the plugin a change-list page, and advances the cursor only in the acknowledging batch. CURSOR_EXPIRED becomes reset: 'expired', which tells the plugin to do a full compare. A periodic sweep recovers a missing marker.
• API. export async function afterCommit(ctx) receives ctx.event with {table, rowClass, grant, reset, changes[{subject, kind, version, at}], hasMore, attempt} and ctx.changes(table, {since}). Returning acknowledges the page; throwing retries it. Backoff runs from 30 s to 1 h; after 8 failed attempts the table's delivery stops and the person gets Retry. Pages hold 100 changes, bursts are debounced for 2 s, the loop cap is 30 runs a minute, and runs get the JS fuel limits and 60 s.
• Writes. With a live grant, writes in check_scope apply unattended, signed by the app agent; with Allow editing scope covers a plugin's provider extras on rows (provider id, ETag, baseline) #1849 that includes provider extras. Everything else waits for review: Apply, "Allow all edits by this view on this table" (grant via: "hook-review"), or Decline.
• Loops. Echoes are dropped by matching the Loro version the hook wrote, not by skipping everything the app agent signed. That way, edits a person makes in the plugin's own view still reach the hook.
• Rollout. Behind --plugin-after-commit (off on develop). No data migration. Views that already have a live grant are backfilled.

Product questions for Michiel

These are in the doc and in a comment on #1851:

1. Does adding a plugin as a table's view also let it follow changes while the tab is closed? A: yes, in the same dialog. B: a separate menu switch. Recommendation: A.
2. Where do proposed background edits wait? A: per table, on the plugin's tab. B: per plugin, on the Installation page. Recommendation: A.
3. What does someone see when a plugin's hook keeps failing? A: a quiet warning with Retry. B: also a notification. Recommendation: A.
4. While a proposal waits, does the plugin keep getting new changes for that table? A: no, it pauses and catches up afterwards. B: yes, proposals pile up. Recommendation: A.

No UI changes, so there are no screenshots.

🤖 Generated with Claude Code

[michielbdejong]

Michiel's decisions (via the coordination session), all as recommended in the design:

1. Following changes: adding a plugin as a table's view also lets it follow changes while the tab is closed, in the same step. The "Let edit rows?" dialog gains a line saying so, and both Allow editing and Read-only turn it on.
2. Where proposed edits wait: per table, as a bar on the plugin's tab (" wants to change 3 rows": Apply / "Allow all edits by this view on this table" / Decline), plus a count on the Installation page.
3. A plugin that keeps failing: a quiet warning mark on the tab and on the Installation page, with Retry. No notification.
4. New changes while a proposal waits: the plugin pauses on that table and catches up after the proposal is answered.

Implementation follows behind --plugin-after-commit (Claude, atomic-server worker).

[joepio]

Trekmeester: included in batch #1915 (run 36779344325). It lands with it when green; if this PR's own tests fail there, I take it out and say why here.

[joepio]

Trekmeester: included in batch #1947 (run 36781515104; #1915 had been merged without it). It lands when that run is green; if this PR breaks something there, I take it out and say why here.

[joepio]

Merged into develop through batch #1947 (squash 1f892aa); this head was verified as part of it. Closing.

---

Generated by Claude Code