mikser-io 11.2.2 → 11.3.1

package/docs/decisions/0008-mcp-ui-action-delivery.md

@@ -0,0 +1,281 @@
+# ADR-0008 — MCP-UI: spec-compatible shell + `tools/call` delivery + optional webhook
+
+**Status:** Superseded
+**Date:** 2026
+**Supersedes:** —
+**Superseded by:** MCP Apps (SEP-1865), implemented in `mikser-io-mcp-app`
+
+## Why this is kept
+
+Archived here because the index row above it linked to this file in the
+`mikser-io-mcp` repository, and the surface moved on to `mikser-io-mcp-app`,
+taking the file with it — leaving core's own decision log with a dead link and
+a hole at 0008.
+
+Most of it was right, which is the interesting part. What survived into
+`mikser-io-mcp-app` is the shape decided here: a static shell resource
+declared as the tool's `_meta.ui.resourceUri`, per-call fragments delivered as
+data rather than markup, clicks arriving as an ordinary `tools/call` against
+an app-only tool, and the declared action list as the authorization boundary.
+
+Two things did not.
+
+**The webhook handler.** `mcpUi.handler.url` forwarded the action to an
+external endpoint, and the ADR argued this respects ADR-0001 because the
+application logic stays outside mikser. The logic did; the URL did not. It
+was an MCP concern sitting in the engine, read by nothing but the MCP
+surface — a field core carried on behalf of one plugin. It is gone, and what
+it reached for is a layout sidecar instead: `<layout>.js` beside the template,
+exporting `call` / `read` / `list`, running in the project rather than at the
+end of an HTTP hop.
+
+**The package.** A host for applications wants a route whose tool list *is*
+the surface, and `mikser_app_action` is app-callable by specification — it has
+no business appearing on the agent's endpoint. So the surface left
+`mikser-io-mcp` for `mikser-io-mcp-app`, and `mcpUi` became `mcpApp`.
+
+One earlier draft of this ADR, on the since-deleted `feat/mcp-ui-handler`
+branch of this repository, is worth one line because the error is easy to
+repeat: it had the iframe POST its action to mikser, reasoning the fetch is
+same-origin because the iframe is served from mikser's origin. Under MCP Apps
+the iframe's CSP is `default-src 'none'; connect-src 'none'` — there is no
+network inside it at all, same-origin included. `postMessage` to the host is
+the only way out. The version below had already corrected that to
+`tools/call`.
+
+## Context
+
+ADR-0007 (`MCP-UI: layouts as the agent's UI surface`) introduced the idea that mikser layouts can serve as the agent's UI surface inside an MCP host. The `mikser_preview_ui` tool renders an `mcpUi`-decorated layout against an entity and returns HTML for the host to surface as a sandboxed iframe. The user interacts with the iframe — clicks Approve, fills a form, picks a status — and the click needs to get back to mikser as a structured tool result.
+
+Three facts about the surrounding ecosystem shape this decision:
+
+1. **The MCP Apps spec ([2026-01-26](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx)) defines how iframe-to-server delivery works.** The iframe runs as an MCP client speaking JSON-RPC over `window.parent.postMessage` to the host. The host's "AppBridge" translates `tools/call` frames into real MCP tool calls on the existing transport. Every conformant host (Goose, ChatGPT/Apps SDK, mcp-ui's reference host, basic-host, VS Code Insiders) implements this same pattern.
+
+2. **The spec mandates the iframe is cross-origin from the host with a restrictive default CSP.** "The Host and the Sandbox MUST have different origins." Default CSP when `ui.csp` is omitted: `default-src 'none'; connect-src 'none'`. So a `fetch` to mikser from inside the iframe — even on the same machine — is blocked by the browser. The only outbound channel is `postMessage`.
+
+3. **The spec mandates that UI is delivered as a static *resource*, not inline tool-result HTML.** Tools that want UI declare `_meta.ui.resourceUri` on their tool definition, pointing at a `ui://` resource with `mimeType: 'text/html;profile=mcp-app'`. Spec-conformant hosts fetch that resource once via `resources/read`, load it in a sandboxed iframe, then push the tool's per-call result to the iframe via `ui/notifications/tool-result`. Empirically, hosts like basic-host display tools that lack `_meta.ui.resourceUri` as plain text rather than rendering an iframe — even if `content[0]` declares `mimeType: 'text/html'`.
+
+These three facts together rule out two tempting alternatives:
+
+- **An in-process HTTP endpoint that the iframe POSTs to**, with a server-minted "callId" as the capability URL. Prototyped on `feat/mcp-ui-handler`, ruled out — incompatible with `connect-src 'none'`, invisible to the host's consent/audit surface, inverts every other MCP App implementation in the ecosystem.
+- **Returning the rendered HTML inline as `content[0].text` and trusting hosts to render it.** Initially shipped in 8.0.x; surfaced as the symptom "basic-host received the tool result but shows it as text, not an iframe." Spec-conformant hosts need the resource URI on the tool definition; they ignore content with `mimeType: 'text/html'` when no resource URI is set.
+
+Separately, productized workflows want to intercept the action server-side without forcing the agent to learn application-specific schemas — a CRM, support system, or admin tool wants to receive the click, do its work, and return a domain-specific result. Pure relay (mikser returns the click data, agent decides what `approve` means) is right for AI-native workflows; webhook delegation (mikser forwards the click to an external URL) is right for productized ones. We want both, without turning mikser into a workflow engine.
+
+## Decision
+
+### Part A — Rendering: static shell resource + structured tool result
+
+**A1. Mikser ships a single static UI resource: `ui://mikser/preview-ui-shell`.**
+
+```js
+mcp.registerResource(
+    'mikser-preview-ui-shell',
+    'ui://mikser/preview-ui-shell',
+    { mimeType: 'text/html;profile=mcp-app', ... },
+    async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: 'text/html;profile=mcp-app', text: SHELL_HTML }],
+    }),
+)
+```
+
+The shell is ~120 lines of self-contained HTML+JS implementing the MCP Apps protocol:
+
+- Sends `ui/initialize` to the host on load (2-second timeout, fails open if no host replies).
+- Listens for `ui/notifications/tool-result`. Reads `structuredContent.html` from the result and injects it into a `#mikser-ui-root` div. Re-executes any `<script>` tags the layout brought (innerHTML doesn't execute embedded scripts by default).
+- Exposes `window.sendAction(action, payload?)` — the API layouts use to deliver clicks back as `tools/call` against `mikser_ui_action`. The shell tracks `entityId` and `layoutId` from the tool result, so layouts don't have to.
+- Renders an in-iframe debug panel showing every protocol event with timestamps — so authors can see exactly where the round-trip fails on hosts that don't bridge.
+
+The shell is static. It does not change between tool calls, between entities, or between mikser versions. It is a fixed bundle of protocol plumbing.
+
+**A2. `mikser_preview_ui` declares `_meta.ui.resourceUri` pointing at the shell.**
+
+```js
+mcp.registerTool('mikser_preview_ui', {
+    description: '...',
+    inputSchema: { entityId, mode },
+    _meta: {
+        ui: { resourceUri: 'ui://mikser/preview-ui-shell' },
+    },
+}, handler)
+```
+
+This is the spec-mandated signal that this tool renders UI. Hosts that implement MCP Apps fetch the resource once via `resources/read` and use it as the iframe template for every call to this tool. Hosts that don't implement MCP Apps display `content[0].text` as plain text (the fallback path; better than nothing).
+
+**A3. The tool result returns content + `structuredContent`.**
+
+```jsonc
+{
+    "content": [
+        { "type": "text", "text": "<rendered fragment>", "mimeType": "text/html" }
+    ],
+    "structuredContent": {
+        "entityId": "/blog/launch.md",
+        "layoutId": "/layouts/mcp-ui/post-approval.hbs",
+        "mode": "approval",
+        "html": "<rendered fragment>",
+        "mcpUi": { "actions": [...], "sandbox": [...], "actionTool": "mikser_ui_action" }
+    },
+    "_meta": { "mcpUi": { ... } }
+}
+```
+
+`content[0].text` is the fallback for non-UI hosts. `structuredContent` is what the host passes to the iframe via `ui/notifications/tool-result`. The shell reads `structuredContent.html` and injects it; it reads `entityId` and `layoutId` to scope subsequent `sendAction` calls.
+
+**A4. Layouts are body fragments, not full HTML documents.**
+
+The shell wraps `<!DOCTYPE>` / `<html>` / `<head>` / `<body>` around the injected content. Layouts produce a fragment containing inline `<style>`, body content, and optional inline `<script>`. The script can call `sendAction(action, payload?)` directly — it's exposed on `window` by the shell. No protocol code, no `ui/initialize`, no RPC helper, no postMessage shape.
+
+Compare a layout authored before this ADR (~85 lines) with one authored after (~40 lines): everything below `<style>` stays; everything above `<style>` and the entire 50-line protocol `<script>` block disappears.
+
+### Part B — Action delivery: `tools/call` against `mikser_ui_action` (visibility=['app'])
+
+**B1. Mikser registers a separate, app-callable tool: `mikser_ui_action`.**
+
+```js
+mcp.registerTool('mikser_ui_action', {
+    description: '...',
+    inputSchema: { entityId, layoutId, action, payload },
+    _meta: { ui: { visibility: ['app'] } },
+}, handler)
+```
+
+`visibility: ['app']` makes the tool invisible to the agent — it never appears in the agent's tool surface — but callable from inside iframes via the host's AppBridge. The agent sees the result as a normal tool turn in its conversation.
+
+**B2. The action allow-list is the auth boundary.**
+
+`mikser_ui_action`'s handler looks up the layout by `layoutId`, reads its `mcpUi.actions` list, and rejects any action not in that list with an error result. This is the single place where layout-declared "you can do these things" meets iframe-supplied "I want to do this thing." Unknown actions never reach pure relay, never reach `handler.url`.
+
+**B3. There is no callId, no signature, no token on this channel.**
+
+The host's MCP transport is already authenticated. The visibility flag already gates which tools the iframe can invoke. The action allow-list already scopes what the iframe can ask for. Layered defenses; no per-call crypto.
+
+**B4. There is no in-process HTTP endpoint for action delivery.**
+
+`/api/mcp-ui/action/...` does not exist. Adding one would create a second delivery path with a different auth model, double the test surface, and offer no benefit on conformant hosts (CSP blocks the fetch) or non-conformant ones (the iframe wouldn't render anyway). One channel, one auth model.
+
+### Part C — Optional webhook handler
+
+**C1. Layouts may declare a `handler` block in their `mcpUi` frontmatter.**
+
+```yaml
+---
+match: "@/articles/*"
+mcpUi:
+  mode: approval
+  actions: [approve, reject, request-changes]
+  sandbox: [allow-scripts]
+  handler:
+    url:     https://app.example.com/mikser-actions
+    secret:  ${MIKSER_HANDLER_SECRET}    # optional, enables HMAC signing
+    timeout: 5000                        # optional, ms; default 5000
+---
+```
+
+When `handler.url` is set, `mikser_ui_action`'s handler forwards the action data to that URL instead of returning the pure-relay payload. The handler's JSON response body becomes the tool result.
+
+**C2. The forwarded request is a standard webhook.**
+
+```http
+POST https://app.example.com/mikser-actions
+Content-Type: application/json
+X-Mikser-Signature: sha256=...
+X-Mikser-Request-Id: <opaque uuid for idempotency>
+X-Mikser-Layout-Id: /layouts/mcp-ui/post-approval.hbs
+X-Mikser-Mode: approval
+
+{
+    "entityId": "/documents/blog/launch.md",
+    "layoutId": "/layouts/mcp-ui/post-approval.hbs",
+    "action":   "approve",
+    "payload":  {},
+    "mode":     "approval",
+    "timestamp": "2026-06-07T15:00:00Z"
+}
+```
+
+`X-Mikser-Signature` is HMAC-SHA256 of the request body using `handler.secret`. Receivers verify before processing. If `secret` is unset, no signature is sent — fine for development; not recommended in production.
+
+**C3. The handler's JSON response is the tool result.**
+
+```json
+{
+    "ok": true,
+    "summary": "Committed to main; deployment queued (build #4821).",
+    "url": "https://app.example.com/deploys/4821",
+    "_meta": { "buildId": 4821 }
+}
+```
+
+Mikser passes this through to the agent unchanged. The agent composes its next message from it. No domain knowledge in mikser.
+
+**C4. Handler failures fall back to pure relay.**
+
+Network error, timeout, non-2xx response, non-JSON response: mikser logs a warning and resolves the tool call with the default `{ entityId, action, payload }` plus a `handlerError` field carrying the failure reason. The user's click is never lost.
+
+```json
+{
+    "entityId": "/documents/blog/launch.md",
+    "action":   "approve",
+    "payload":  {},
+    "handlerError": "Handler timeout (5000ms) — https://app.example.com/mikser-actions"
+}
+```
+
+**C5. The handler block is the entire extension surface.**
+
+Mikser does not learn about action semantics — what `approve` means, what `request-changes` should do, where the result goes. Adding that knowledge to mikser would violate ADR-0001 (`Mikser is the content layer of the application, not the app`). The webhook contract IS the extension point; if you want behaviour, write a service.
+
+## Consequences
+
+**Easier:**
+
+- Spec compliance is unconditional. Spec-conformant hosts (Goose, ChatGPT, mcp-ui's reference host, basic-host, VS Code Insiders) render mikser layouts as iframes correctly. No host-specific shims.
+- Layouts shrink dramatically — no more per-layout 50-line protocol boilerplate. Author content + inline styles + click handlers; the shell handles everything else. Comparing the blog example's `post-approval.hbs` v8.0.x vs v8.1.0: ~85 lines → ~40 lines, roughly half. The protocol bug surface collapses to one place.
+- The action allow-list + visibility flag are the entire auth model. No bespoke crypto primitive to debug.
+- One static resource served forever; one tool result shape that's the same on every call. Cacheable, predictable, testable.
+
+**Harder:**
+
+- Layouts authored before 8.1.0 — full HTML documents with embedded `ui/initialize` and RPC plumbing — need rewriting. The new shape is mechanically simpler but it is *not* drop-in compatible with 8.0.x layouts. Mikser's blog example layouts ship pre-rewritten as canonical references.
+- Hosts that haven't implemented MCP Apps (`Claude Desktop` per the open `upstream-host` bug [anthropics/claude-ai-mcp#165](https://github.com/anthropics/claude-ai-mcp/issues/165)) show the iframe as raw text. There is no fallback — and that's deliberate. Both alternatives explored above introduce more problems than they solve.
+- The shell's debug panel is on by default. Production use will want to either gate it behind a query param or remove it entirely. Tracked as a follow-up.
+
+## Examples
+
+See `documentation/mcp.md` "Layout frontmatter and MCP-UI" — every worked example was rewritten when this ADR landed. Each one collapses to roughly 30-50 lines including inline styles.
+
+## Alternatives considered
+
+**Direct HTTP from iframe to mikser (capability URL pattern).** Prototyped on `feat/mcp-ui-handler`. Random callId, single-use, action allow-list, loopback bind — textbook capability URL, genuinely secure against CSRF/replay/unknown-actions. Ruled out because:
+
+1. Default MCP Apps CSP is `connect-src 'none'` — the browser blocks the fetch on conformant hosts.
+2. The iframe is cross-origin from the host by spec — there is no "same-origin" with mikser to leverage.
+3. The action bypasses the host's audit/consent surface.
+4. It inverts the direction of every other MCP App implementation, making mikser layouts non-portable.
+
+**Returning HTML inline in `content[0].text` with `mimeType: 'text/html'`.** Shipped initially in 8.0.x. Surfaced as the symptom "basic-host received the tool result, displayed it as plain text, never rendered an iframe." Conformant hosts read `_meta.ui.resourceUri` off the tool definition (static) to decide what iframe template to load — they do not infer it from response content. The fix is the resource pattern in Part A.
+
+**Per-layout tools (`mikser_preview_approval`, `mikser_preview_edit`, etc.) each with their own static `_meta.ui.resourceUri`.** Cleaner mapping but tool count grows with layout count, and the agent has to learn which tool handles which mode. The shell-as-template approach keeps the agent's tool surface stable (one `mikser_preview_ui` for all UIs) while still satisfying the spec's static-URI requirement.
+
+**Dual-channel (postMessage primary, HTTP fallback).** Rejected as "no legacy" — two delivery paths means two auth models, two test surfaces, two failure modes to debug, and no host where both are needed. Pick one channel; pick the one the spec specifies.
+
+**Built-in action vocabulary (mikser knows what `approve` / `reject` mean).** Rejected. This is the application layer; mikser is the content layer (ADR-0001). The agent owns semantics by default; `handler.url` is the escape hatch for productized cases.
+
+**Server-side handler scripts (layouts ship a `handler:` callback in JS).** Rejected. Same reasoning — mikser would become a workflow engine. External webhooks compose; in-mikser handlers would couple action behaviour to mikser deployment.
+
+**Per-action handlers (`handler` is a map: `{ approve: url1, reject: url2 }`).** Rejected as YAGNI. Single URL with the action in the payload is enough — the receiver multiplexes.
+
+## Watch for drift
+
+These are the failure modes this decision is protecting against. If you see them, push back.
+
+- **The shell grows application-specific knowledge.** Someone proposes "the shell could pre-format the date before injecting" or "the shell could add a global retry banner." Refuse. The shell is protocol + injection + sendAction relay. Application concerns live in layouts.
+- **A second action-delivery channel sneaks in.** Someone notices `mikser_ui_action` doesn't work on a non-conformant host and proposes adding an HTTP endpoint as a "fallback." Don't. The 8.1.0 design is one channel by deliberate choice.
+- **`_meta.ui.resourceUri` drift on the tool definition.** Someone removes it or changes it to point at something dynamic. Spec-conformant hosts will stop rendering iframes — they only read this field at tool-list time, not per-call.
+- **Layouts start re-implementing the protocol.** Someone writes a layout with its own `ui/initialize` handshake "for control." That layout will fight the shell. The shell exposes `sendAction`; that's the entire contract a layout uses.
+- **The visibility flag drifts on `mikser_ui_action`.** If `_meta.ui.visibility` is removed or changed to `['model', 'app']`, the tool leaks into the agent's surface — it'll appear as an action the agent can take "out of context" without any iframe ever rendering. Strict `['app']`.
+- **Action vocabulary creeps into core.** Someone proposes a built-in `approve` semantic so simple layouts don't need a handler. Refuse; that's application-layer logic.
+- **Per-action handler URLs.** Someone proposes `handler: { approve: '...', reject: '...' }`. Refuse. One URL, the action goes in the payload, the receiver routes.
+- **Retry / backoff on the handler.** Mikser doesn't retry. If the handler is down, the user re-clicks.
+- **Persistent pending state.** There is no pending state — `mikser_preview_ui` returns synchronously and the shell handles per-render state in the iframe. Don't add a "pending action" table.

package/docs/decisions/README.md

@@ -33,7 +33,7 @@ Decisions don't expire. They get **superseded** when we learn enough to change t
 | [0005](./0005-engine-infrastructure-runs-before-plugin-hooks.md) | Engine infrastructure (journal, catalog) is ready before any plugin hook runs; `runtime.update` is upsert; `useSource` codifies the folder-of-files pattern | Accepted |
 | [0006](./0006-when-to-add-to-core.md) | The five-test check for adding capability to the engine vs. shipping it as a plugin | Accepted |
 | [0007](./0007-references-declaration-and-expansion.md) | Entity references: `$`-prefixed declaration (canonical on disk, normalized for render/SDK) and `expand` resolution (inline, GET-cacheable, engine-level `runtime.refs` drives invalidation + live-expand) | Accepted |
-| [0008](https://github.com/almero-digital-marketing/mikser-io-mcp/blob/main/documentation/decisions/0008-mcp-ui-action-delivery.md) | MCP-UI rendering + action delivery: static shell resource at `ui://mikser/preview-ui-shell` (declared as `_meta.ui.resourceUri` on `mikser_preview_ui`) hosts the [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) protocol; per-call rendered fragments delivered via `structuredContent` and `ui/notifications/tool-result`; the shell exposes `window.sendAction()` so layouts are content-only HTML. Clicks ride `tools/call` against `mikser_ui_action` (`_meta.ui.visibility = ['app']`). Action allow-list is the auth boundary. Optional `mcpUi.handler.url` forwards the action to an external webhook (HMAC-signed if `handler.secret` set); handler failures fall back to pure relay. No HTTP delivery surface. Lives in [`mikser-io-mcp`](https://github.com/almero-digital-marketing/mikser-io-mcp). | Accepted |
+| [0008](./0008-mcp-ui-action-delivery.md) | MCP-UI rendering + action delivery: static shell resource declared as `_meta.ui.resourceUri`, per-call fragments via `structuredContent`, clicks riding `tools/call` against an app-only tool, declared action list as the authorization boundary. The shape survived; the `mcpUi.handler.url` webhook did not — an MCP concern in the engine, replaced by a layout sidecar. The surface moved to [`mikser-io-mcp-app`](https://github.com/almero-digital-marketing/mikser-io-mcp-app) and `mcpUi` became `mcpApp`. Archived here because the file left with it. | Superseded |
 | [0009](./0009-database-engine-substrate.md) | Sqlite is the engine's persistence substrate. Single `runtime/mikser.sqlite` file holds catalog/refs/manifest/journal as `mikser_entities` / `mikser_refs` / `mikser_snapshots` / `mikser_journal` tables. Plugins register schemas via `registerSchema(name, sql)` + `useDatabase()`. Sift→SQL translator with indexed pushdown, LRU cache for `findById`, worker-side read-only sqlite for sync template helpers, chunked journal walks + `iterateEntities` streaming, `useJournal` auto-persist (mutate the yielded entity; no explicit `updateEntry` needed), `--resume` after interrupted cycles. Replaces `Map<id, entity>` + NDJSON across every engine subsystem. | Accepted |
 | [0010](./0010-plugin-bundles-and-inline-options.md) | Plugin bundles + factory-call form + inline options. Plugins are imported by name and called as factories; `plugins: []` carries factory returns, never strings. Lifecycle plugins are `(options) => (core) => void`; renderers return `{name, options, load?, render?}`; postprocessors return `{name, options, output?, setup?, postprocess, teardown?}`. Per-plugin config moved off `runtime.config.<plugin>` — it arrives as the factory arg and is passed as `config` to `load`/`render`/`setup`/`postprocess`. | Accepted |
 | [0011](./0011-served-entities-expose-deployed-urls.md) | File and resource entities expose deployed URLs. References to served files (image/video/PDF) are `$`-keyed **served paths** (`/img/X.jpg`, `/media/clip.mp4` — the path content authors, = the entity's `meta.url`), resolving through a new `refFilter` `{ 'meta.url': … }` clause backed by an indexed `meta_url` column (schema 9.0.1 → 9.0.2). No collection-prefixed ids leak into content. (Id-refs were tried and rejected — gpoint references content by served path and its `/media/**` `resources()` library means the entity only exists because content references `/media/…`.) The `files`/`resources` plugins stamp `meta.url`, the `assets` plugin stamps `meta.presets` — so expanding a ref yields the served entity's URL set instead of a string to reconstruct. Base-relative in the live catalog (host-agnostic; consumer holds `base`), absolute in static renders (baked from `runtime.options.url`, so logic-less consumers — email, RSS, foreign apps — read a whole URL); `lookupUrl` render helper resolves a ref to `meta.url` or a named preset. SDK collapses `assetUrl(source, preset, {ext})` into one `url(ref)` join + a dev-mode SPA-fallback detector. *("Served entity" — file/resource/preset — avoids colliding with the `assets` plugin's own "asset reference" term.)* | Accepted (proven against gpoint) |

package/docs/diagnostics.md

@@ -771,6 +771,29 @@ layout it went through. Entities with no layout — a copied asset, a
 `files()` passthrough — stay out, or the answer would be "everything,
 always", which is the same non-answer as "nothing" with the sign flipped.
 
+**`recordNoOutput(id)` — the one write on this facade a plugin should
+make.** Everything above answers questions; this one tells the manifest
+something only a dispatcher can know: that it looked at an entity and found
+nothing to render it with. The manifest then drops the snapshots that entity
+still holds, and unlinks the files they claim, in its own finalize
+transaction — so the cleanup gets the same guard as every other: a
+destination another entity still claims is never taken away.
+
+It exists because the two states that matter are indistinguishable from
+inside the manifest. An entity whose `layout:` was removed and an asset whose
+preset threw both arrive with no successful render and no destination on their
+catalog row, and pruning on that resemblance deletes the good derivative a
+failed preset exists to keep. So the call is only correct for "I dispatched
+this and matched nothing" — never for a failure, and never for a declaration
+that could not be resolved, since mikser keeps the last good output through an
+error rather than taking the page down. `mikser-io-layouts` makes it; any
+other dispatcher can.
+
+Without it, an entity that stops producing output leaves its page on disk with
+a snapshot still vouching for it — and because the file still matches the hash
+its own render recorded, `--audit-output` reads OK while the site serves
+something the source no longer asks for.
+
 ### `runtime.provenance`
 
 Where a value was **written** — source file, field path, line and column.

package/docs/getting-started.md

@@ -187,8 +187,9 @@ const documents = useCollection(runtime, 'documents')
 //    that's what mikser's normal lifecycle does (anything persisted is
 //    queryable via findEntities). For on-demand renders where the
 //    bytes are the work product and you don't want the metadata row to
-//    accumulate, pass { catalog: false } to opt out. The rendered
-//    output file is kept on disk either way.
+//    accumulate, pass { catalog: false } and the catalog ends the call
+//    exactly as it began it. The rendered output file is kept on disk
+//    either way.
 const { output, entity } = await render({
   id: '/documents/en/report.md',
   type: 'document',
@@ -217,9 +218,24 @@ parallelism within the cycle is governed by `runtime.options.threads`.
 `render` options:
 
 - `timeout` — per-call timeout in ms (default 30_000).
-- `catalog` (default `true`) — keep the entity in the catalog after the
-  render. Pass `catalog: false` to prune the row, useful for on-demand
-  renders where the metadata would just accumulate.
+- `catalog` (default `true`) — let this render's changes reach the catalog.
+  Pass `catalog: false` and the catalog ends the call exactly as it began
+  it: the row that was there goes back as it was, and a row this render
+  created is removed. Useful for on-demand renders where the metadata would
+  just accumulate, and for previews, where the entity you hand in is usually
+  an altered copy (a surface forcing its own layout onto it) that has no
+  business becoming the entity's production state.
+
+  The render still travels the lifecycle, so the copy does reach the row
+  while the render needs it — the pipeline reads it back to resolve the
+  layout. It just does not outlive the call, whether the render succeeds or
+  throws. Nothing is journalled to achieve this, so the file a
+  `save: true, catalog: false` render produced stays on disk.
+
+  `save: false` implies it: a render that keeps nothing on disk has no
+  business moving a row either. Neither combination records a manifest
+  snapshot — a snapshot is a claim about a catalog entity's output, and
+  after a neutral render there is no such entity to speak for.
 - `save` (default `true`) — write the rendered output to disk at
   `<outputFolder>/<entity.destination>`. Pass `save: false` to skip the
   final disk write; the bytes still come back in `output.result` for you

package/docs/plugins.md

@@ -702,7 +702,7 @@ Writes content to a file in a collection folder. The file change is picked up by
 ```
 
 `options` is optional. Strict opt-outs via the literal `false`:
-- `options.catalog: false` — prune the catalog row after render
+- `options.catalog: false` — leave the catalog exactly as the call found it (the row goes back as it was; a row this render created is removed). The output file is kept.
 - `options.save: false` — skip the final disk write (bytes still in the response)
 
 **`GET /<endpoint>/entities/subscribe`**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "11.2.2",
+  "version": "11.3.1",
   "files": [
     "app.js",
     "index.js",

package/src/catalog.js

@@ -191,6 +191,58 @@ function entityToRow(entity) {
     }
 }
 
+// Catalog-neutral renders in flight: entity id -> the row as it stood before
+// the render, or null where there was no row.
+//
+// Module-local rather than a field on runtime, deliberately. useRenderer takes
+// its runtime by injection while this module imports the singleton, so a field
+// there is written on one object and read on another the moment anyone injects
+// anything else — which every unit test does. One owner, and the writer has to
+// come through markNeutralRender.
+const neutralRenders = new Map()
+
+// Ids whose neutral render has finished — successfully or not — and whose
+// entry is therefore the next finalize drain's to clear.
+//
+// Without this the map is a leak of exactly the kind this feature exists to
+// prevent: gpoint-api renders with a fresh uuid per request, so an entry that
+// is only ever removed when a matching write shows up accumulates one row per
+// render for the life of the process. A render that THROWS journals nothing at
+// all, so that is not a hypothetical.
+const settledNeutralRenders = new Set()
+
+/**
+ * Declare that a render of `id` must leave the catalog as it found it, and
+ * hand over the row to put back — or null where there was none.
+ *
+ * Called by useRenderer BEFORE dispatch: the row is written during the cycle
+ * because the pipeline reads it back to resolve the layout, so what makes the
+ * render neutral is the restore afterwards, not a suppressed write.
+ *
+ * @param {string} id
+ * @param {object|null} prior
+ */
+export function markNeutralRender(id, prior) {
+    if (!id) return
+    neutralRenders.set(id, prior ?? null)
+    settledNeutralRenders.delete(id)
+}
+
+/**
+ * Report that the render of `id` has finished, however it finished. The next
+ * finalize drain restores anything it still owes and drops the entry.
+ *
+ * Separate from markNeutralRender because the two happen either side of the
+ * cycle: a render registered while a cycle is running is served by the NEXT
+ * one, so entries cannot simply be cleared at each cycle's end — an unsettled
+ * one is still waiting for its turn.
+ *
+ * @param {string} id
+ */
+export function settleNeutralRender(id) {
+    if (id && neutralRenders.has(id)) settledNeutralRenders.add(id)
+}
+
 // Apply per-cycle journal mutations inside one transaction (per the
 // migration plan's per-phase transaction granularity). Maintains
 // `mikser_refs` alongside `mikser_entities` so refs and entities
@@ -198,14 +250,26 @@ function entityToRow(entity) {
 //
 // better-sqlite3's transaction wrapper is sync-only, so we drain the
 // journal first and then sync-apply in one call.
-async function applyJournalMutations() {
+// `phase` is which drain this is — 'persist' (before render) or 'finalize'
+// (after it). It decides what happens to a catalog-neutral render's entry:
+// the persist drain applies it, because the pipeline reads the row back to
+// resolve the layout and the render fails outright without it; the finalize
+// drain puts the prior row back instead, because by then the render is done
+// and the altered copy has no business outliving it.
+async function applyJournalMutations(phase) {
     const logger = useLogger()
     const refsIndex = useRefsIndex()
     const mutations = []
     for await (const { operation, entity } of useJournal('Catalog')) {
         mutations.push({ operation, entity })
     }
-    if (!mutations.length) return
+    // Ids whose neutral render finished in this cycle. Collected during the
+    // pass and settled inside the same transaction, so no reader ever sees
+    // the altered row.
+    const toRestore = phase === 'finalize' ? new Map() : null
+    // A settled entry is cleared even in a cycle that journalled nothing —
+    // which is precisely the shape a failed render leaves behind.
+    if (!mutations.length && !settledNeutralRenders.size) return
     db.transaction(() => {
         // Two passes, deliberately. indexEntity resolves each $-ref
         // against mikser_entities to record what it bound to, so it has
@@ -217,6 +281,14 @@ async function applyJournalMutations() {
             switch (operation) {
                 case OPERATION.CREATE:
                 case OPERATION.UPDATE:
+                    if (toRestore && neutralRenders.has(entity.id)) {
+                        // A catalog-neutral render's own write, arriving after
+                        // the render. Restoring rather than applying is the
+                        // whole of `catalog: false`.
+                        logger.trace('Database restore after neutral render: %s', entity.id)
+                        toRestore.set(entity.id, neutralRenders.get(entity.id))
+                        break
+                    }
                     logger.trace('Database %s %s: %s', entity.collection, operation, entity.id)
                     stmtUpsert.run(entityToRow(entity))
                     toIndex.push(entity)
@@ -241,9 +313,57 @@ async function applyJournalMutations() {
         // delete-then-insert per source internally, so this stays
         // idempotent across UPDATE.
         for (const entity of toIndex) refsIndex?.indexEntity(entity)
+
+        // Last, so it wins over anything else this batch wrote for the id.
+        for (const [id, prior] of toRestore ?? []) {
+            restoreRow(id, prior, refsIndex)
+            neutralRenders.delete(id)
+            settledNeutralRenders.delete(id)
+        }
+        // Whatever is left over from a render that has finished without
+        // journalling anything for us to undo. Nothing to restore — useRenderer
+        // already put the row back the moment the render settled — so this only
+        // releases the entry.
+        if (toRestore) {
+            for (const id of settledNeutralRenders) neutralRenders.delete(id)
+            settledNeutralRenders.clear()
+        }
     })
 }
 
+// Put a row back exactly as it stood, or remove it where there was none.
+//
+// Sync, and assumes it is already inside a transaction — both callers are.
+// Writes nothing to the journal on purpose: a journal entry would dispatch
+// another render, and a journaled DELETE drags the manifest's file cleanup
+// with it, which would unlink the output a `save: true, catalog: false`
+// render was asked to produce.
+function restoreRow(id, prior, refsIndex = useRefsIndex()) {
+    if (prior) {
+        stmtUpsert.run(entityToRow(prior))
+        refsIndex?.indexEntity(prior)
+    } else {
+        stmtDelete.run(id)
+    }
+    cacheEvict(id)
+}
+
+/**
+ * Restore an entity to the row it had before a catalog-neutral render, or
+ * remove it if it had none. Called by useRenderer as soon as the render
+ * resolves, so a caller awaiting `render()` sees the catalog as it was; the
+ * finalize drain then does the same again for the write that lands after.
+ *
+ * @param {string} id
+ * @param {object|null} prior - the row as it stood, or null if there was none
+ */
+export function restoreEntity(id, prior) {
+    if (!id || !db?.isOpen) return
+    const refsIndex = useRefsIndex()
+    // mikser's db.transaction RUNS the function; it does not return one.
+    db.transaction(() => restoreRow(id, prior, refsIndex))
+}
+
 onLoaded(async () => {
     db = useDatabase()
     if (!db) {
@@ -329,7 +449,7 @@ onLoaded(async () => {
 })
 
 onPersist(async () => {
-    await applyJournalMutations()
+    await applyJournalMutations('persist')
 })
 
 onFinalize(async () => {
@@ -353,7 +473,7 @@ onFinalize(async () => {
     // render reads the catalog), and journal consumers are named and
     // independent, so a second pass only ever picks up what the first could
     // not have seen.
-    await applyJournalMutations()
+    await applyJournalMutations('finalize')
 
     // Checkpoint the WAL so the main file size stays representative
     // and external tools (mikser --audit-output on a separate run, debug

package/src/manifest/cycle.js

@@ -57,20 +57,51 @@ onFinalize(async () => {
         deletedIds.push(entity.id)
     }
 
+    // Every destination claimed by a render task this cycle — whether it
+    // succeeded, was skipped as current, or failed.
+    //
+    // This is deliberately WIDER than renderedEntries, and the width is the
+    // safety. The staleness test below asks "is this row's destination one its
+    // entity still claims", and all three outcomes answer yes:
+    //
+    //   skipped   the manifest said the output was already current, which is
+    //             an assertion that it BELONGS. One entity can match several
+    //             layouts, and a dependency change invalidates them
+    //             independently — so a cycle where layout A re-renders and
+    //             layout B is skipped is ordinary, and reading B's silence as
+    //             "no longer produced" would unlink a live page.
+    //   failed    a failed render writes no snapshot on purpose, so the last
+    //             good bytes survive. Treating the gap as abandonment
+    //             destroys exactly what that rule protects.
+    const claimedByRenderTasks = new Map()
     for await (const { output, entity, deps } of useJournal('Output', [OPERATION.RENDER])) {
-        // A render that wrote NOTHING has no snapshot to record. A snapshot is
-        // the manifest's claim that a file exists at a destination — it is what
-        // --audit-output verifies and what invalidation compares against — so a
-        // `save: false` render (a preview: bytes back to the caller, nothing on
-        // disk) recording one makes the manifest assert a file nobody wrote.
+        if (entity?.id && entity.destination) {
+            if (!claimedByRenderTasks.has(entity.id)) claimedByRenderTasks.set(entity.id, new Set())
+            claimedByRenderTasks.get(entity.id).add(entity.destination)
+        }
+        // A catalog-neutral render leaves no snapshot. A snapshot is the
+        // manifest's claim about a CATALOG ENTITY's output — it is what
+        // --audit-output verifies and what invalidation compares against — and
+        // both halves of `neutral` end the call with no such entity to speak
+        // for.
         //
-        // Observed on a live site: an MCP app rendered on demand left
+        // For `save: false` the claim is false outright: nothing was written.
+        // Observed on a live site — an MCP app rendered on demand left
         // /internal/customer-registration.html claimed and absent, and the
-        // audit went red for a page that was never supposed to exist. The
-        // entity is simply left unrecorded, which is also the truthful state
-        // for invalidation — nothing was produced, so the next real build has
-        // nothing to reuse.
-        if (entity?.options?.save === false) continue
+        // audit went red for a page that was never supposed to exist.
+        //
+        // For `save: true, catalog: false` the file is real but the entity is
+        // deliberately not mikser's to track, and recording it is what makes
+        // the two accounts disagree: the manifest holds a snapshot whose
+        // entity no longer exists. It also breaks the caller directly —
+        // invalidation compares against the snapshot, finds the destination
+        // already current, and SKIPS the render, so the next call for the same
+        // id gets no output at all.
+        //
+        // Leaving it unrecorded is the truthful state for invalidation either
+        // way: mikser is not tracking this output, so there is nothing to
+        // reuse and nothing to verify.
+        if (entity?.options?.neutral) continue
         if (output?.success && !output.skipped) {
             renderedEntries.push({ entity, deps, metaReads: output.metaReads,
                                    consumedReads: output.consumedReads })
@@ -119,13 +150,25 @@ onFinalize(async () => {
 
     // 2b. Pagination shrunk — drop children whose destination wasn't
     // re-emitted this cycle.
-    const childrenToDelete = []   // [{id, destination, reason}]
+    const snapshotsToDelete = []   // [{id, destination}] — rows to drop by PK
+    // Ids that DEPART with their snapshot: a pagination child that no longer
+    // exists. Feeds `goingAway`, which asks "is this destination still claimed
+    // by something that survives" — an id-level question, and the right one
+    // for an entity that is gone.
+    const departingIds = new Set()
+    // Rows dropped for a destination their own entity no longer produces, as
+    // `id \t destination`. Deliberately NOT an id: an entity whose
+    // destination merely MOVED is still very much here, and calling it
+    // departed would let another entity's cleanup unlink a destination this
+    // one still claims.
+    const droppedClaims = new Set()
     for (const [parentId, keep] of newDestinationsByParent) {
         const rows = m._stmtSelectByParent.all(parentId)
         for (const row of rows) {
             if (keep.has(row.destination)) continue
             filesToUnlink.push({ destination: row.destination, reason: 'Pagination shrunk' })
-            childrenToDelete.push({ id: row.id, destination: row.destination })
+            snapshotsToDelete.push({ id: row.id, destination: row.destination })
+            departingIds.add(row.id)
         }
     }
 
@@ -134,14 +177,88 @@ onFinalize(async () => {
         const rows = m._stmtSelectByParent.all(parentId)
         for (const row of rows) {
             filesToUnlink.push({ destination: row.destination, reason: 'Pagination dropped' })
-            childrenToDelete.push({ id: row.id, destination: row.destination })
+            snapshotsToDelete.push({ id: row.id, destination: row.destination })
+            departingIds.add(row.id)
+        }
+    }
+
+    // 2c'. Destination moved — a SURVIVING entity no longer produces a
+    // destination it used to.
+    //
+    // Change a layout's `destination:` template, or flip `cleanUrls`, and the
+    // entity keeps its id and renders to a new path. Nothing before this
+    // noticed: the snapshot table is keyed by (id, destination), so recording
+    // the new render INSERTS a second row rather than replacing the first, and
+    // the old row goes on claiming the old file forever.
+    //
+    // Worse than it sounds, because the state is self-consistent and therefore
+    // silent: the stale file is still on disk, still matches the hash its own
+    // render recorded, so --audit-output reports OK — 0 missing, 0 orphaned —
+    // while the site serves a page the project no longer produces. Verified on
+    // a two-build fixture: one entity, two snapshots, two files, green audit.
+    //
+    // The comparison is against the SET of destinations the id claimed this
+    // cycle, never a single value. One entity can legitimately claim several —
+    // one per matched layout — and taking the last one to render as "the"
+    // destination would delete the others' output on every build. See
+    // claimedByRenderTasks above for why a skipped or failed task counts as a
+    // claim.
+    //
+    // Two ways in, and the difference is who observed what.
+    //
+    // An entity with render tasks is compared against what they claimed —
+    // that is the moved-destination case above.
+    //
+    // An entity that produces nothing at all has no tasks to compare against,
+    // so it cannot be recognised from here: an asset whose preset threw looks
+    // exactly the same, and pruning on that resemblance deletes the good
+    // derivative a failed preset exists to keep. So the dispatcher says it
+    // outright, through manifest.recordNoOutput, and an empty claim set means
+    // every destination the entity used to hold is stale. Reported by
+    // mikser-io-layouts when an entity it dispatched matched no layout; the
+    // call is general, and any other dispatcher can make it.
+    const claims = new Map(claimedByRenderTasks)
+    for (const id of m._noOutputIds) {
+        // A task contradicts the report — something did render, so believe
+        // what happened over what was predicted.
+        if (!claims.has(id)) claims.set(id, new Set())
+    }
+    m._noOutputIds.clear()
+
+    for (const [id, claimed] of claims) {
+        if (deleted.has(id)) continue
+        // An entity that renders nothing takes its paginated children with
+        // it. There are no tasks left to own them, and 2b/2c reach children
+        // only when a render told them this cycle's page count — so for this
+        // entity they never fire, and the children would be left claiming
+        // files nothing produces. Where tasks DID run, children stay with
+        // 2b/2c, which know about shrinking in a way this pass does not.
+        const rows = claimed.size
+            ? m._stmtDestinationsById.all(id)
+            : m._stmtSelectByIdOrParent.all(id, id)
+        for (const row of rows) {
+            if (claimed.has(row.destination)) continue
+            if (claimed.size && row.parent) continue
+            filesToUnlink.push({
+                destination: row.destination,
+                reason: claimed.size ? 'Destination moved' : 'Entity renders nothing',
+            })
+            snapshotsToDelete.push({ id: row.id, destination: row.destination })
+            if (row.parent) {
+                // A child is genuinely gone, not moved — its id departs.
+                departingIds.add(row.id)
+            } else {
+                droppedClaims.add(`${row.id}\t${row.destination}`)
+            }
         }
     }
 
-    // Everything whose snapshot this pass removes: deleted entities, their
-    // paginated children, and children dropped by a pagination shrink.
+    // Ids whose snapshots this pass removes ENTIRELY: deleted entities and
+    // their paginated children. Not the moved claims — those belong to
+    // entities that are still here, and `droppedClaims` carries them at
+    // (id, destination) granularity instead.
     const goingAway = new Set(deleted)
-    for (const { id } of childrenToDelete) goingAway.add(id)
+    for (const id of departingIds) goingAway.add(id)
     for (const parentId of deleted) {
         for (const row of m._stmtSelectByParent.all(parentId)) goingAway.add(row.id)
     }
@@ -194,7 +311,9 @@ onFinalize(async () => {
         // snapshot as a claimant would keep every shrunk page on disk
         // forever.
         const stillClaimed = m._stmtSelectByDestination.all(destination)
-            .filter(row => row.id !== undefined && !goingAway.has(row.id))
+            .filter(row => row.id !== undefined
+                && !goingAway.has(row.id)
+                && !droppedClaims.has(`${row.id}\t${destination}`))
         if (stillClaimed.length) {
             // Keep the file — deleting a live page's output is worse than any
             // staleness — but do NOT let the state go quiet. The bytes on
@@ -251,7 +370,7 @@ onFinalize(async () => {
             m._stmtDeleteByIdOrParent.run(id, id)
         }
         // 3b. Pagination children cleanup.
-        for (const { id, destination } of childrenToDelete) {
+        for (const { id, destination } of snapshotsToDelete) {
             m._stmtDeleteByPK.run(id, destination)
         }
         // 3c. Record successful renders.

package/src/manifest/index.js

@@ -84,6 +84,7 @@ export function createManifest(db) {
         stmtSelectByIdOrParent,
         stmtDeleteByIdOrParent,
         stmtSelectByParent,
+        stmtDestinationsById,
         stmtSelectAll,
         stmtCount,
         stmtEntityInputHashes,
@@ -92,6 +93,10 @@ export function createManifest(db) {
         stmtSnapshotsWithLayout,
         edgeCandidates,
     } = prepareStatements(db)
+    // Ids a dispatcher reported as producing nothing this cycle. Owned by
+    // this instance rather than the module, so a test that builds its own
+    // manifest gets its own set. Drained and cleared by onFinalize.
+    const noOutputIds = new Set()
     const manifest = {
         // Look up a previously-recorded entry by entity (or by an
         // object with `{id, destination}`). Returns the snapshot, or
@@ -548,6 +553,29 @@ export function createManifest(db) {
         },
 
         // Drop all snapshots owned by entity id (direct outputs and any
+        // Report that a dispatcher looked at this entity and found nothing
+        // to render it with — no layout matched, no preset claimed it.
+        //
+        // The distinction this exists to draw is between "produced no output
+        // this cycle" and "no longer produces output at all". They are
+        // indistinguishable from inside the manifest: an asset whose preset
+        // threw and an entity whose `layout:` was removed both arrive with no
+        // successful render and no destination on their catalog row, and
+        // guessing from that signal deletes the good derivative a failed
+        // preset is explicitly meant to keep. Only the dispatcher knows which
+        // it is, so only the dispatcher can say.
+        //
+        // Recorded, not applied. The removal joins onFinalize's single
+        // transaction and its unlink path, so it gets the same
+        // still-claimed-by-a-survivor guard as every other cleanup — a
+        // destination two entities write is not this one's to take away.
+        //
+        // Per cycle: onFinalize clears the set after draining it. Saying it
+        // twice for one entity is harmless.
+        recordNoOutput(id) {
+            if (id) noOutputIds.add(id)
+        },
+
         // paginated children whose `parent` is set to this id). Returns
         // the destinations that were removed so callers can unlink the
         // corresponding files when desired. Two queries (SELECT for
@@ -794,6 +822,8 @@ export function createManifest(db) {
         _stmtSelectByIdOrParent: stmtSelectByIdOrParent,
         _stmtDeleteByIdOrParent: stmtDeleteByIdOrParent,
         _stmtSelectByParent:     stmtSelectByParent,
+        _noOutputIds:            noOutputIds,
+        _stmtDestinationsById:   stmtDestinationsById,
         _stmtSelectByDestination: stmtSelectByDestination,
         _stmtDeleteByDestination: stmtDeleteByDestination,
         _stmtDeleteByPK:         stmtDeleteByPK,

package/src/manifest/statements.js

@@ -82,6 +82,13 @@ export function prepareStatements(db) {
     const stmtSelectByParent = db.prepare(`
         SELECT id, destination FROM mikser_snapshots WHERE parent = ?
     `)
+    // Every destination one entity claims. An entity legitimately claims
+    // several — one per matched layout, and one per page when paginated — so
+    // "the destinations this id produced" is a SET, never a single value, and
+    // that is the whole reason this query exists separately from stmtLookup.
+    const stmtDestinationsById = db.prepare(`
+        SELECT id, destination, parent FROM mikser_snapshots WHERE id = ?
+    `)
     const stmtSelectAll = db.prepare(`
         SELECT id, destination, inputHash, inputParts, outputHash, refClosure, metaReads, consumedReads, renderedAt, parent
         FROM mikser_snapshots
@@ -179,6 +186,7 @@ export function prepareStatements(db) {
         stmtSelectByIdOrParent,
         stmtDeleteByIdOrParent,
         stmtSelectByParent,
+        stmtDestinationsById,
         stmtSelectAll,
         stmtCount,
         stmtEntityInputHashes,

package/src/plugins/api.js

@@ -1036,7 +1036,7 @@ export function api(options = {}) {
                     // straight to render(entity, options). Defaults match
                     // mikser's lifecycle (save and keep the catalog row);
                     // strict opt-outs via the literal `false`:
-                    //   options.catalog: false → prune the catalog row
+                    //   options.catalog: false → leave the catalog as found
                     //   options.save:    false → skip the final disk write
                     //                            (bytes still in the response)
                     const { options = {}, ...entityShape } = req.body

package/src/render.js

@@ -506,13 +506,16 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
      * Two control flags mirror mikser's default-keep-everything behavior;
      * both opt-out via strict `=== false`:
      *
-     * - `catalog: true` (default) — keep the entity in the catalog after
-     *   the render. Pass `catalog: false` to prune the catalog row;
-     *   useful for on-demand renders where the metadata row would just
-     *   accumulate. Requires `save: false` — the prune goes through the
-     *   journal, and a DELETE takes the manifest's file cleanup with it,
-     *   so it is only safe for a render that wrote nothing. With
-     *   `save: true` the row is kept and a warning is logged.
+     * - `catalog: true` (default) — pass `catalog: false` and the catalog
+     *   ends the call exactly as it began it: the row that was there is put
+     *   back as it was, and a row this render created is removed. The render
+     *   still travels the lifecycle, so the caller's copy — usually altered,
+     *   since an on-demand surface forces its own layout onto it — does reach
+     *   the row while the render needs it; it just does not outlive the call.
+     *   Combines with either `save`, which is the point: gpoint-api renders
+     *   its emails with `save: true, catalog: false` — the file is wanted, the
+     *   row is not. `save: false` implies it, since a render that keeps
+     *   nothing on disk has no business moving a row either.
      * - `save: true` (default) — write the rendered output to disk at
      *   `<outputFolder>/<entity.destination>`. Pass `save: false` to
      *   skip the final disk write; the bytes still come back via
@@ -539,31 +542,40 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
      * @param {object} entity                - any entity-shaped object
      * @param {object} [opts]
      * @param {number}  [opts.timeout]       - override the default timeout
-     * @param {boolean} [opts.catalog=true]  - keep the catalog row after render
+     * @param {boolean} [opts.catalog=true]  - let this render's changes reach
+     *                                          the catalog; false restores it
      * @param {boolean} [opts.save=true]     - write the rendered output to disk
      * @returns {Promise<{output, entity}>}
      */
     async function render(entity, { timeout = defaultTimeout, catalog = true, save = true } = {}) {
-        // Was this row already in the catalog BEFORE the render? `catalog:
-        // false` means "do not leave a row behind", and that is only the
-        // render's to decide for a row the render created. Asked here, before
-        // the render puts one there.
+        // What the catalog held before this render touched it.
         //
-        // Without it, `catalog: false` deleted whatever it was handed: a
-        // preview of an EXISTING entity pruned the real row, so the entity
-        // vanished from the site while its file sat on disk — no change set,
-        // no cycle, and the removal logged only at debug. It cost a day to
-        // find, in a form that rendered once and then answered "Entity not
-        // found".
-        // Imported HERE, not at the top: catalog.js reaches back into this
-        // module, and a static import makes that cycle load-bearing at
+        // Read BEFORE dispatch, because the render itself overwrites it: the
+        // entity has to travel the lifecycle to render at all, and the
+        // pipeline reads the row back to resolve the layout, so suppressing
+        // that write outright fails the render with "requested layout X but
+        // produced no output". The row is written, used, and then put back.
+        //
+        // Imported here rather than at the top: catalog.js reaches back into
+        // this module, and a static import makes that cycle load-bearing at
         // module-evaluation time — it surfaced as "Cannot access 'schemas'
         // before initialization" in three unrelated test files.
-        const preexisting = catalog === false && entity?.id
-            ? Boolean(await (await import('./catalog.js')).findById(entity.id))
-            : false
+        const neutral = save === false || catalog === false
+        // Restoring is about a ROW, so it needs an id; the flag itself does
+        // not, and the manifest reads the flag to decide whether to record a
+        // snapshot. Keeping the two apart means an id-less entity — which has
+        // no row to put back — still gets the rest of neutrality.
+        let priorRow = null
+        if (neutral && entity?.id) {
+            const { findById, markNeutralRender } = await import('./catalog.js')
+            priorRow = findById(entity.id)
+            // Handed over before dispatch, so it is in place however early the
+            // cycle starts. The catalog's finalize drain is where the row goes
+            // back for good — see applyJournalMutations.
+            markNeutralRender(entity.id, priorRow)
+        }
 
-        const result = await new Promise((resolve, reject) => {
+        const dispatched = new Promise((resolve, reject) => {
             const correlationId = randomUUID()
             // Engine-set fields live under entity.options. The caller's
             // render(entity, { save: false }) becomes
@@ -580,6 +592,10 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
                     ...entity.options,
                     correlationId,
                     ...(save === false ? { save: false } : {}),
+                    // Marks every journal entry this render produces, however
+                    // many phases later they arrive, as belonging to a
+                    // catalog-neutral call.
+                    ...(neutral ? { neutral: true } : {}),
                 },
             }
             pending.push({
@@ -593,32 +609,28 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
             if (!cycleRunning) setImmediate(runBatch)
         })
 
-        if (catalog === false) {
-            // Prune the row through the journal, so the DELETE lands in
-            // sqlite at onPersist alongside the CREATE that put it there.
-            // Strict equality — null / "false" / 0 keep the row.
-            //
-            // Only when `save` is also false. A DELETE carries the
-            // manifest's file cleanup with it, which unlinks the render's
-            // output; that is correct for an entity that produced no file
-            // and wrong for one that did. `catalog: false, save: true`
-            // therefore keeps its row, and says so rather than dropping
-            // the output on the floor.
-            if (preexisting) {
-                // Someone else's row. It was here before this render and is
-                // not this render's to remove.
-                useLogger()?.debug(
-                    'render: catalog:false ignored for %s — the entity was already in the catalog',
-                    result.entity.id,
-                )
-            } else if (save === false) {
-                await runtime.delete(result.entity)
-            } else {
-                useLogger()?.warn(
-                    'render: catalog:false ignored for %s — it needs save:false, ' +
-                    'because pruning the row also unlinks the rendered output',
-                    result.entity.id,
-                )
+        let result
+        try {
+            result = await dispatched
+        } finally {
+            // In a finally, because a render that THROWS has still altered the
+            // row on its way through — an unrenderable entity leaves the
+            // catalog holding the caller's copy of it, which is the same
+            // damage as a successful render leaving its layout behind.
+            if (neutral && entity?.id) {
+                // Put the row back for whoever is awaiting us. The finalize
+                // drain does it again, and has to: it runs after the render and
+                // would otherwise re-apply the altered copy over this one. Both
+                // restore the same prior row, so their order does not matter.
+                //
+                // Deliberately not journaled. A journal entry would dispatch
+                // another render, and a journaled DELETE drags the manifest's
+                // file cleanup along with it — which would unlink the very file
+                // a `save: true, catalog: false` render was asked to produce.
+                // That coupling is why this used to refuse `save: true`.
+                const { restoreEntity, settleNeutralRender } = await import('./catalog.js')
+                restoreEntity(entity.id, priorRow)
+                settleNeutralRender(entity.id)
             }
         }