mikser-io 9.0.0 → 9.0.1

package/10.0-PLAN.md

@@ -37,7 +37,7 @@ When the working signals dominate over a sustained period of real use, v10 desig
 
 ## Why v10 (not 9.x)
 
-The 9.0 plan deliberately deferred mikser-to-mikser composition to v10. The reasoning is in `9.0-PLAN.md` under "Out of scope":
+The 9.0 design deliberately deferred mikser-to-mikser composition to v10. The reasoning:
 
 > Cross-instance concerns (discovery, peer identity, routing, cross-mikser refs, watch propagation, liveness, partition behavior, peer auth) belong to a distributed-systems substrate that iterates at "we hit a production partition bug" speed, not at engine-substrate speed. Folding any of it into `mikser-io` would re-fail ADR-0006 test #5 (release cadence) the moment it ships.
 

package/CLAUDE.md

@@ -10,22 +10,51 @@ paths. No migration markdown. No `task: pool` legacy aliasing for
 `task: inline`. Update READMEs and ADRs in place as source-of-truth
 changes; rewrite, don't supersede. The freedom is the point.
 
-**v9 has to pay out before v10 starts.** Not "ship v9 and start v10."
-**Use v9 in real daily work until the workflow pays out**, then
-v10. The v10 architecture (party-mikser-io) is more fun to design
-than v9 documentation is to write — the gate exists because that
-asymmetry kills projects. Concrete pass/fail signals in
-`10.0-PLAN.md` under "The gate." If a session brings up v10 design
-work, check the gate first; if v9 isn't paying out yet, the
-question to answer is "what about v9 isn't working in daily use?"
-— not "what should v10 look like?"
-
-**Position mikser by what it is, not by speed.** Hugo wins the speed
-race; mikser doesn't compete there. Position: AI-native, lifecycle-
-observable, files-as-source-of-truth, full-cycle introspection. Speed
-claim cap: "fast enough that watch-mode rebuilds feel instant."
-Honest range: 200–800 docs/sec depending on corpus size
-(see `test/perf/`).
+**v9 shipped. The gate now is daily-use payoff, not completion.**
+The engine, every sibling plugin, the agency template — all live.
+The next step isn't "finish v9," it's **use v9 in real daily work
+until the workflow earns the v10 layer**. The v10 architecture
+(party-mikser-io) is more fun to design than v9 dogfooding is to
+sustain — the gate exists because that asymmetry kills projects.
+Concrete pass/fail signals in `10.0-PLAN.md` under "The gate." If
+a session brings up v10 design work, check the gate first; if v9
+isn't paying out yet, the question to answer is "what about v9
+isn't working in daily use?" — not "what should v10 look like?"
+
+**mikser is a mixer.** The name is the architecture. It combines
+inputs (entities — from files, forms, queries, anywhere) through
+configurable rendering pipelines (renderer plugins + task-production
+policies) into outputs of any kind. Static-site generation is the
+canonical recipe — what mikser ships with and what most projects
+use today — but it's a recipe, not the definition. The same
+substrate runs:
+
+- HTML SSG via `layouts` + `renderHbs` (the recipe everything else
+  is currently shaped around)
+- PDFs via `renderHbs` + `post-pdf` (puppeteer-driven)
+- Emails via `renderHbs` → `post-mjml` → `post-email` (chain)
+- 3D renders by composing a hypothetical `renderBlender` against
+  `.blend` entities — same engine, different renderer + recipe
+- Video / audio / archives / data-export — same shape
+
+The engine has no opinion on what a renderer produces. `render.js`
+and `postprocess.js` are abstract worker entries; `manifest.js`
+tracks snapshots of *any* output; refs invalidation re-runs
+*any* render task. SSG is the dominant case in v9 because it's
+where the dogfooding lives, not because the architecture only
+fits there. When proposing changes, hold the broader view: a
+change that helps SSG but blocks the Blender/video/audio/archive
+cases is constraining the engine's actual reach.
+
+**Position mikser by what it is, not by speed.** Hugo wins the
+speed race for SSG specifically; mikser doesn't compete there
+(and "fastest mixer" isn't a useful claim because the bottleneck
+is the renderer, not the engine). Secondary attributes that
+follow from the mixer framing: AI-native, lifecycle-observable,
+files-as-source-of-truth, full-cycle introspection. Speed claim
+cap: "fast enough that watch-mode rebuilds feel instant." Honest
+range: 200–800 docs/sec on the SSG-flavor pipeline depending on
+corpus size (see `test/perf/`).
 
 **Direct critique preferred.** Skip "great question," skip "solid but,"
 skip softening. When something didn't pay off, say so. Match user
@@ -100,7 +129,16 @@ brevity.
   plugins to push onto), late-binding static mount + listen.
 - `logger.js` — pino + pino-pretty (inline) + gauge progress + custom
   Writable for progress coordination + `pino.multistream` for
-  third-party shipping (`runtime.config.logging.transports`).
+  third-party shipping. Two registration surfaces for transports:
+  - `runtime.config.logging.transports` — declarative; user config.
+  - `addLogTransport({ target, options?, level? })` — public export;
+    plugins call this from their factory (queues until logger build)
+    or any later hook (live-rebuilds the multistream + swaps
+    `runtime.engine.logger`). `useLogger()` reads the swap-target
+    fresh on each call so new transports start receiving records
+    immediately. Both surfaces compose; same `{level, target, options}`
+    shape. Enables Better Stack / Datadog / Loki / Axiom / Sentry as
+    standard sibling plugins without engine changes per vendor.
 - `utils.js` — shared pure helpers: `mimeForEntity`, `isLoopback`,
   `expandEntity`, `projectMeta`, `useCollection`, `useRenderer` (via
   render.js), `isTextEntity`, `readEntityContent`, `extractRefs`,
@@ -141,11 +179,35 @@ brevity.
   POSTPROCESS), `ACTION` (sync action types), `TASKS` (`INLINE`/
   `SERIAL`/`WORKER` — dispatch modes).
 
+## Canonical sibling plugins
+
+These ship as separate repos but most projects pull them in. They're
+not bundled because the engine is renderer-agnostic — each plugin
+encodes a particular recipe (SSG, MJML, PDF, email) rather than
+substrate.
+
+- **`mikser-io-layouts`** — the canonical SSG-flavor task-production
+  policy. Owns multi-match layout assignment (`meta.layout` /
+  `meta.layouts` dual key + `autoLayouts` peel ladder), per-layout
+  destination Handlebars templates, collision detection, postprocess
+  chain parsing (filename `name.html-mjml-email.hbs` → `postprocessors:
+  ['mjml','email']` + frontmatter `postprocessor`/`postprocessors`),
+  `inspect()` primitive at `runtime.options.layouts.inspect`. The
+  engine has no opinion on layouts; this plugin is one way of producing
+  render tasks. Other domains (3D rendering, video) would have their
+  own task-production plugins.
+- **`mikser-io-render-{hbs,liquid,eta,markdown,metatext}`** — renderer
+  plugins. `renderHbs` is bundled in core; the rest are siblings.
+- **`mikser-io-post-{mjml,pdf,email}`** — postprocessor plugins,
+  composable in chains (see `documentation/rendering.md#postprocess`).
+- **`mikser-io-mcp`** — AI tooling surface (ADR-0006 test #5).
+- **`mikser-io-vector`** — vector index over the catalog.
+- **`mikser-io-forms`** — HTTP form receivers → entities.
+- **`mikser-io-schemas`** — TypeScript type generation from entity meta.
+
 ## Plugin map (`src/plugins/`)
 
 - `documents` — file→entity sync for the documents collection
-- `layouts` — layout matching + sitemap + `inspect()` primitive
-  (exposed at `runtime.options.layouts.inspect`)
 - `files` — file→entity sync for the files collection
 - `assets` — asset references and copy
 - `resources` — resource references
@@ -160,11 +222,75 @@ brevity.
 - `observer` / `mapper` / `validator` / `commands` / `shares` —
   utility plugins
 
+## Built-in content providers (`src/plugins/providers/`)
+
+The substrate-side `readEntityContent(entity)` dispatches by URI
+scheme. Two schemes are handled inline by built-in providers
+(no separate package required, ships with mikser-io):
+
+- **No scheme / plain path / `file://`** — filesystem read. Lives
+  inline in `src/utils.js readEntityContent` because the engine
+  already touches the filesystem everywhere.
+- **`http://` / `https://`** — `src/plugins/providers/http.js`.
+  Conditional GET with ETag + Last-Modified, in-memory response
+  cache, inflight coalescing on the same URL, binary mirror to
+  `runtime/http-cache/<sha-of-url>.<ext>`, operator-supplied
+  headers via `entity.meta.httpHeaders`, configurable timeout via
+  `entity.meta.httpTimeoutMs`. Test affordance:
+  `__resetHttpCacheForTests()` clears the module-level caches
+  between unit tests.
+
+Any other scheme (`gdrive://`, `notion://`, `s3://`, …) routes
+through the dynamic-import-by-name path — `mikser-io-provider-<scheme>`
+must be installed as a sibling package and export a top-level
+`read(entity)` function. See ADR-0010 / the gdrive provider for
+the convention.
+
+## Multi-emitter collections (sweep ownership)
+
+Collections like `documents` / `files` / `assets` aren't owned by a
+single plugin. The file source (via `useSource`) emits into them
+from its scanned folder, but other plugins legitimately emit into
+the same collection: `mikser-io-csv` fans CSV rows into `documents`,
+a gdrive sync would emit there too, an API endpoint can push into
+`files`. The catalog has no opinion on emitter identity — only on
+collection.
+
+The delete sweep MUST respect that. `sweepDeleted(collection,
+scanned, onDelete, ownerPrefix)` requires `ownerPrefix` (typically
+`absFolder` for file sources, `layoutsFolder` for layouts) and only
+considers entities whose `entity.uri` is rooted under that prefix.
+Foreign-emitter entities have a different `uri` shape:
+- CSV row entities: empty `uri` (synthetic — meta is the content)
+- HTTP-fetched CSV parent: `uri = 'https://…'`
+- gdrive-sourced docs: `uri = 'gdrive://…'`
+
+…and the LIKE clause excludes them. Without the scope, every cycle's
+file-source sweep silently wipes every co-collection emitter's
+entities. Throwing instead of silently sweeping the whole collection
+is intentional — this used to be a class-of-bugs landmine. If you're
+writing a new source-shaped plugin, the scoping is mandatory.
+
+Test coverage: `test/unit/source-sweep.test.js`.
+
 ## Naming conventions
 
 - **Engine state** at `runtime.<name>` — `runtime.refs`, `runtime.catalog`.
 - **Plugin surfaces** at `runtime.options.<plugin>` —
   `runtime.options.preview`, `runtime.options.layouts.inspect`.
+- **Reachability:** `runtime.options.url` is the engine's resolved
+  public URL (from `--url` or `config.url`, trailing slash stripped,
+  validated). Plugins that need external reachability — webhook
+  receivers, absolute links in emails, MCP preview URLs returned to
+  agents, forms share links — read this. Standard gating pattern:
+  ```js
+  const canPush = runtime.options.url?.startsWith('https://')
+  if (canPush) registerWebhookAt(`${runtime.options.url}/api/X/webhook`)
+  else         setupPollingFallback()
+  ```
+  `runtime.options.port` is the internal listener port (kept for
+  loopback/dev URL building); `runtime.options.url` is the external
+  origin. When in doubt: external = `url`, internal = `port`.
 - **Engine functions** as module-level exports from `mikser-io`:
   `import { queryEntities, subscribe, useRenderer, useCollection,
   readEntityContent, isTextEntity } from 'mikser-io'`.
@@ -326,6 +452,22 @@ There is **no `--mcp` CLI flag**. Activation is plugin-presence only.
 - **New lifecycle hook?** Almost certainly no. Existing hooks cover
   all known patterns. If you think you need one, post the use case
   to ADR-0006 review.
+- **New content source (gdrive, notion, s3, github, …)?** Two
+  things ship together:
+  - A regular lifecycle plugin (the sync — emits entities into the
+    catalog, sets `entity.uri = '<scheme>://...'` so the dispatch
+    knows where to route reads).
+  - A named export `read(entity)` from the same package, which
+    must be named `mikser-io-provider-<scheme>` so the engine can
+    find it. `readEntityContent(entity)` parses the scheme out of
+    `entity.uri`, dynamic-imports the package, calls its `read`.
+    No registry, no descriptor — same package-name convention as
+    `mikser-io-render-*` and `mikser-io-post-*`.
+  Built-in: plain local paths (no scheme) and `file://` URIs are
+  read via `fs.readFile` directly — no provider package needed for
+  the canonical local-filesystem case. `entity.content` already
+  populated is a fast-path that skips the dispatch entirely (for
+  small remote docs eager-fetched at sync time).
 
 ## Test suites
 
@@ -342,6 +484,48 @@ There is **no `--mcp` CLI flag**. Activation is plugin-presence only.
   + clean-build timing). `SIZE=realistic` + entity count knobs
   documented in **Perf**.
 
+## Dev workspace
+
+The siblings live side-by-side under `/Users/dick/Projects/mikser/`
+and share an npm workspace declared at the parent's `package.json`:
+
+```json
+{
+  "private": true,
+  "workspaces": ["mikser-io", "mikser-io-*"]
+}
+```
+
+`npm install` at that root hoists everything: each sibling's
+`node_modules/mikser-io` (and any other cross-workspace dep)
+becomes a symlink to the working copy. The whole tree runs
+against ONE module instance of mikser-io.
+
+**This isn't optional ergonomics — it's correctness.** Plugins
+use `AsyncLocalStorage` (currently `queryContext` for sidecar
+findEntities tracking; the schema-version meta could grow more).
+Without workspace deduplication, npm 7+ auto-installs the peer
+dep into each sibling's own `node_modules`. Layouts'
+`import { queryContext } from 'mikser-io'` then resolves to its
+bundled copy — a different AsyncLocalStorage instance than the
+engine uses. Sidecar queries don't get tracked → no `query`
+edges in `mikser_snapshots.refClosure` →
+`manifest.queryAffected` returns empty → aggregate layouts
+(index pages, sitemaps, RSS feeds) never invalidate when new
+matching entities land. Silent broken-incremental.
+
+`test/scenarios/_harness.js` also auto-coalesces (replaces any
+real `mikser-io-layouts/node_modules/mikser-io` directory with a
+symlink to MIKSER_ROOT on every `setupFixture`) as a backstop —
+the scenarios pass with or without the workspace, but the
+workspace is the canonical setup. Same shape applies to any
+future sibling that uses `queryContext` or other module-level
+state from mikser-io.
+
+For production consumers (someone `npm install mikser-io
+mikser-io-layouts` in their own project), npm resolves both from
+the consumer's own project tree — no duplication, no bug.
+
 ## Reference
 
 - `documentation/architecture.md` — module map (audit before relying
@@ -350,5 +534,8 @@ There is **no `--mcp` CLI flag**. Activation is plugin-presence only.
 - `documentation/configuration.md` — config reference
 - `documentation/api-reference.md` — public API
 - `test/perf/` — render-pipeline perf rig
-- Sibling repos: `mikser-io-mcp`, `mikser-io-vector`, `mikser-io-schemas`,
+- Sibling repos: `mikser-io-layouts` (canonical SSG-flavor render-task
+  production policy), `mikser-io-mcp`, `mikser-io-vector`,
+  `mikser-io-schemas`, `mikser-io-forms`, `mikser-io-post-{mjml,pdf,email}`,
+  `mikser-io-render-{eta,liquid,markdown,metatext}`,
   `mikser-io-sdk-{api,react,svelte,vue,vector}`, `mikser-io-example-blog`

package/README.md

@@ -50,6 +50,28 @@ Build mikser into the parts of your application that are content-shaped. Keep th
 
 **Open source.** MIT-licensed, on GitHub, no telemetry, no auth wall, no SaaS dependency. What you see is what runs.
 
+## Mix content from anywhere, ship to anywhere
+
+A real content stack pulls from more than one system. Marketing copy lives in a CMS or a spreadsheet. Prices and stock live in an ERP. Hero images live in a DAM. Editorial pages live in markdown files in the repo. Most teams either pick one tool and contort the rest to fit it, or build sync services that copy everything into one database — and then more sync services when things drift out of sync.
+
+Mikser is built around a different bet: **one queryable substrate that any source can pour into, and any frontend can read from.**
+
+**Any source.** Provider plugins let you treat external systems as content sources. A Google Sheet, an ERP feed, a Drive folder, a Notion database, an HTTP webhook, the local repo's `.md` files — each becomes a stream of entities flowing into mikser's catalog with the same shape. The authoring tool doesn't change. The editorial workflow doesn't change. The team writing product copy in Google Sheets keeps writing product copy in Google Sheets — mikser just notices when they save.
+
+**Cross-source composition through references.** Mikser tracks references between entities the way a graph database does. A product page can declare `$marketing` pointing at a row pulled from a spreadsheet, `$pricing` at a record pulled from your ERP, `$hero` at an asset pulled from your DAM. A single API call from your frontend asks for the product page *with* its referenced data — and gets the page, the marketing copy, the price, and the hero image merged into one response. One round trip, not three or four, and no consumer-side join logic to maintain.
+
+**Live updates are uniform across every source.** Edit a cell in the spreadsheet, change a price in the ERP, replace an asset in the DAM — the pages depending on those entities update within seconds, in every frontend connected to mikser's live channel. You don't write per-source invalidation; mikser already knows which pages reference what.
+
+**Your frontend is whatever you want.** Mikser exposes the catalog over HTTP (and over MCP, for AI agents). You query it from React, Vue, Svelte, SvelteKit, Next.js, an iOS app, a kiosk — anything that speaks HTTP. The framework SDKs (`mikser-io-sdk-react`, `mikser-io-sdk-vue`, `mikser-io-sdk-svelte`) make the calls feel native, but they're optional. Headless CMSes free you from the database lock. Frameworks like Astro free you from one kind of authoring lock. Mikser frees you from both at once: **any source on the input side, any framework on the output side.**
+
+What this looks like in practice:
+
+- Marketing edits product copy in Google Sheets, prices come from your ERP, both flow into the same product page in your storefront — changes appear within seconds, without your e-commerce team writing webhook handlers or cache-invalidation logic.
+- A SaaS pulls customer-facing release notes from `release-notes/*.md` in the repo and feature flags from LaunchDarkly; both render in a dashboard built in the team's own React stack, not a framework somebody else picked.
+- A magazine pulls editorial articles from local markdown, contributor bios from Notion, sponsorship info from Airtable, and renders the same article surface across web, email (MJML), and PDF — one catalog, one set of references, three outputs.
+
+Adding a source is mechanical. See [`mikser-io-csv`](https://github.com/almero-digital-marketing/mikser-io-csv) (any HTTP-served CSV, with live polling), [`mikser-io-provider-gdrive`](https://github.com/almero-digital-marketing/mikser-io-provider-gdrive) (Google Drive), and the built-in `http` provider for the shape. If a system has an API, it can be a mikser source, usually in well under 100 lines.
+
 ## Built for AI-assisted development
 
 Files-as-source isn't just a portability story — it makes the project unusually friendly to AI coding agents. There's a static-time half (the agent reads your tree the way it reads any repo — no DB connection, no schema upload, no sandboxed query layer to learn) and a runtime half (when the agent needs to write or render, mikser ships its own MCP server in core, so it talks to the live engine instead of a parallel REST shim you have to maintain).
@@ -150,6 +172,7 @@ The engine is what stays stable — the lifecycle, the catalog, the file-based c
 |---|---|
 | [`mikser-io-vector`](https://github.com/almero-digital-marketing/mikser-io-vector) | OpenAI embeddings + semantic search (sqlite-vec or pgvector) |
 | [`mikser-io-schemas`](https://github.com/almero-digital-marketing/mikser-io-schemas) | Zod-backed entity validation + auto-generated TypeScript declarations for the SDK. Auto-detects `$`-keyed references and warns on broken ones — see [ADR-0007](./documentation/decisions/0007-references-declaration-and-expansion.md) |
+| [`mikser-io-forms`](https://github.com/almero-digital-marketing/mikser-io-forms) | Public form-submission endpoints. POST → captcha + schema validation → write a document file plus uploaded files to disk; the `documents` / `files` plugins pick them up via their normal watch loop. Composes with `mikser-io-schemas` for schema-by-name; built-in captcha providers (Google v2/v3, hCaptcha, Turnstile) plus a custom-verify escape hatch |
 | [`mikser-io-archive`](https://github.com/almero-digital-marketing/mikser-io-archive) | Persist matching entities to YAML — audit trail, versioned content history, downstream export |
 | `mapper` | Run config-supplied transforms over matched entities each cycle (in-core, generic transformation layer) |
 | [`mikser-io-live`](https://github.com/almero-digital-marketing/mikser-io-live) | Lightweight dev server with browser auto-refresh — pair with `--watch` for the classic save→reload loop |

package/index.js

@@ -28,7 +28,7 @@ export { documents }     from './src/plugins/documents.js'
 export { files }         from './src/plugins/files.js'
 export { frontMatter }   from './src/plugins/front-matter.js'
 export { json }          from './src/plugins/json.js'
-export { layouts }       from './src/plugins/layouts.js'
+// layouts moved to sibling: import from 'mikser-io-layouts'
 export { mapper }        from './src/plugins/mapper.js'
 export { observer }      from './src/plugins/observer.js'
 export { preview }       from './src/plugins/preview.js'

package/package.json

@@ -1,12 +1,12 @@
 {
 	"name": "mikser-io",
-	"version": "9.0.0",
+	"version": "9.0.1",
 	"description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
 	"main": "index.js",
 	"exports": {
-		".":            "./index.js",
+		".": "./index.js",
 		"./package.json": "./package.json",
-		"./*":          "./*"
+		"./*": "./*"
 	},
 	"scripts": {
 		"debug": "node --no-warnings app.js --server --watch --working-folder test/fixture",
@@ -61,6 +61,7 @@
 		"express": "^5.2.1"
 	},
 	"devDependencies": {
+		"@ai-sdk/openai": "^3.0.71",
 		"fluent-ffmpeg": "^2.1.3",
 		"mikser-io-decap": "file:../mikser-io-decap",
 		"mikser-io-post-mjml": "file:../mikser-io-post-mjml",

package/src/engine.js

@@ -5,7 +5,7 @@ import { existsSync } from 'fs'
 import _ from 'lodash'
 import Piscina from 'piscina'
 import runtime from './runtime.js'
-import { onInitialize, onInitialized, onRender, onCancel, onCancelled, onFinalized, onLoaded, onBeforePostprocess, onPostprocess, postprocessEntities } from './lifecycle.js'
+import { onInitialize, onInitialized, onLoad, onRender, onCancel, onCancelled, onFinalized, onLoaded, onBeforePostprocess, onPostprocess, postprocessEntities } from './lifecycle.js'
 import { useJournal, updateEntry } from './journal.js'
 import { globby } from 'globby'
 import { OPERATION, TASKS } from './constants.js'
@@ -178,6 +178,39 @@ export async function setup(options) {
     // bring-up logs come after the folder-info lines.
     setupServer()
 
+    // Public URL resolution. CLI --url wins; otherwise read runtime.config.url
+    // populated by the user's mikser.config.js. Stamped on runtime.options.url
+    // (no trailing slash) for plugins to consume in their onLoaded.
+    //
+    // Plugins that need external reachability (webhook receivers, absolute
+    // links in emails, MCP preview URLs, forms share links) read this. The
+    // standard gating pattern is:
+    //
+    //     const canPush = runtime.options.url?.startsWith('https://')
+    //     if (canPush) registerWebhookAt(`${runtime.options.url}/api/X/webhook`)
+    //     else         setupPollingFallback()
+    //
+    // Runs at onLoad — after config.js fires its onLoad (which populates
+    // runtime.config) and before any plugin's onLoaded.
+    onLoad(async () => {
+        const logger = useLogger()
+        const cli = runtime.options.url
+        const cfg = runtime.config?.url
+        const raw = cli ?? cfg
+        if (raw == null || raw === '') {
+            runtime.options.url = undefined
+            return
+        }
+        try {
+            new URL(raw)
+        } catch (err) {
+            throw new Error(`Invalid --url / config.url value: ${raw} (${err.message})`)
+        }
+        runtime.options.url = String(raw).replace(/\/+$/, '')
+        logger.info('Public URL: %s%s', runtime.options.url,
+            runtime.options.url.startsWith('https://') ? ' (webhook-capable)' : ' (http; plugins will not enable push webhooks)')
+    })
+
     onLoaded(async () => {
         const logger = useLogger()
         logger.debug(runtime.options, 'Mikser options')
@@ -479,15 +512,17 @@ export async function setup(options) {
 
         const tasks = []
         for await (const { entity, options, context, output } of useJournal('Queuing postprocess', [OPERATION.RENDER], signal)) {
-            if (output?.success && options.postprocessor) {
-                const ext = await resolveOutputExt(options.postprocessor)
-                // Engine swaps the extension on whatever destination the
-                // entity carries. Routing semantics (cleanUrls folder
-                // structure, alternate placements, etc.) are whoever-set-
-                // entity.destination's responsibility — typically the
-                // layouts plugin during layout-match. The postprocess
-                // subsystem has no opinion about routing.
-                const destination = changeExtension(entity.destination, ext)
+            // Read the postprocessor chain. layouts plugin carries
+            // it as `options.postprocessors` (array, normalized); the
+            // singular `options.postprocessor` is a back-compat alias
+            // for the head of the chain. Empty chain → no postprocess.
+            const chain = options.postprocessors ?? (options.postprocessor ? [options.postprocessor] : [])
+            if (output?.success && chain.length) {
+                // The FINAL destination extension is the last stage's
+                // `output:`. Intermediate stages' extensions are used
+                // only for scratch path naming inside src/postprocess.js.
+                const finalExt = await resolveOutputExt(chain[chain.length - 1])
+                const destination = changeExtension(entity.destination, finalExt)
 
                 tasks.push({
                     entity: {
@@ -496,7 +531,11 @@ export async function setup(options) {
                         destination
                     },
                     options: {
-                        postprocessor: options.postprocessor,
+                        // Singular kept for back-compat with the worker
+                        // serialization shape; chain is the source of
+                        // truth.
+                        postprocessor: chain[0],
+                        postprocessors: chain,
                         tasks: options.tasks,
                         // When the originating render call passed
                         // `save: false`, the layouts plugin wrote the

package/src/lifecycle.js

@@ -300,17 +300,21 @@ export function onSync(name, callback) {
 export function onValidate(operations, callback) {
     const logger = useLogger()
     runtime.validators.push(async (entry) => {
-        if (operations.indexOf(entry.operation) != -1) {
-            try {
-                const message = await callback(entry)
-                if (message) {
-                    logger.warn('Validation problem: [%s] %s %s', entry.operation, entry.entity.name, message)
-                }
-                return true
-            } catch (err) {
-                logger.error('Validation error: [%s] %s %s', entry.operation, entry.entity.name, err.message)
-                return false
+        // Abstain explicitly when this validator isn't scoped to the
+        // entry's operation — returning undefined here means "pass"
+        // under runtime.validate's abstain-is-pass contract. The early
+        // return makes that intent legible instead of relying on a
+        // fall-through.
+        if (operations.indexOf(entry.operation) === -1) return
+        try {
+            const message = await callback(entry)
+            if (message) {
+                logger.warn('Validation problem: [%s] %s %s', entry.operation, entry.entity.name, message)
             }
+            return true
+        } catch (err) {
+            logger.error('Validation error: [%s] %s %s', entry.operation, entry.entity.name, err.message)
+            return false
         }
     })
 }

package/src/logger.js

@@ -37,6 +37,31 @@ import { onLoad } from './lifecycle.js'
 // want visibility above info noise but aren't warnings.
 const CUSTOM_LEVELS = { notice: 35 }
 
+// Plugin-side log transport registry — paired with `addLogTransport`
+// below. Two-state lifecycle:
+//
+//   - Before createMikserLogger() runs (the plugin factory phase, when
+//     mikser.config.js is being import()'d and the factories embedded
+//     in `plugins: []` are calling addLogTransport synchronously), the
+//     entries land in pendingTransports. createMikserLogger drains it
+//     alongside the declarative runtime.config.logging.transports when
+//     it builds the multistream.
+//
+//   - After createMikserLogger() has run, `currentStreams` and
+//     `currentLevel` are populated. Any later addLogTransport call
+//     (e.g. from a plugin's onLoaded hook, or a deferred integration)
+//     builds the new stream, pushes it onto currentStreams, and swaps
+//     runtime.engine.logger to a fresh pino instance backed by the
+//     updated multistream. useLogger() reads runtime.engine.logger
+//     fresh on each call, so the new transport starts receiving
+//     records immediately for every subsequent log call.
+//
+// The shape `{ level?, target, options? }` mirrors what
+// runtime.config.logging.transports already accepts.
+const pendingTransports = []
+let currentStreams = null
+let currentLevel   = 'info'
+
 // Per-level icons prepended via pino-pretty's messageFormat. Empty
 // strings for levels we don't want to decorate — debug/trace are noisy
 // enough already. messageFormat receives `log.level` as a number, so we
@@ -135,22 +160,26 @@ export function createMikserLogger(level = 'info') {
 
     const streams = [{ level, stream: prettyStream }]
 
-    // Mikser-config-driven third-party transports. Each entry is
-    // `{ level?, target, options? }` — same shape pino.transport()
-    // accepts. The transport spawns a worker; if its module fails to
-    // load (missing dep, bad config), we surface it to stderr and keep
-    // the terminal stream alive rather than crashing the engine.
-    const transports = runtime.config?.logging?.transports ?? []
-    for (const t of transports) {
-        try {
-            const stream = pino.transport({ target: t.target, options: t.options })
-            streams.push({ level: t.level ?? level, stream })
-        } catch (err) {
-            process.stderr.write(
-                `Logger: failed to load transport "${t.target}": ${err.message}\n`
-            )
-        }
+    // Two sources of transports merged into one list:
+    //
+    //   - runtime.config.logging.transports (declarative — user-config-
+    //     driven). The historical surface; still works unchanged.
+    //   - pendingTransports (plugin-side, drained here). Plugin factories
+    //     that called addLogTransport at config-load time land here.
+    //
+    // Each entry is `{ level?, target, options? }` — same shape
+    // pino.transport() accepts. Transport workers that fail to load
+    // (missing dep, bad config) surface to stderr but don't crash the
+    // engine — the terminal stream stays alive.
+    const declared = runtime.config?.logging?.transports ?? []
+    for (const t of [...declared, ...pendingTransports]) {
+        const s = buildTransportStream(t, level)
+        if (s) streams.push(s)
     }
+    pendingTransports.length = 0
+
+    currentStreams = streams
+    currentLevel   = level
 
     return pino(
         {
@@ -161,6 +190,62 @@ export function createMikserLogger(level = 'info') {
     )
 }
 
+// Construct a multistream entry for a transport descriptor. Returns
+// null when the underlying pino.transport() call throws (missing
+// dependency, bad options) — caller treats null as "skip".
+function buildTransportStream(entry, defaultLevel) {
+    try {
+        return {
+            level:  entry.level ?? defaultLevel,
+            stream: pino.transport({ target: entry.target, options: entry.options }),
+        }
+    } catch (err) {
+        process.stderr.write(
+            `Logger: failed to load transport "${entry.target}": ${err.message}\n`
+        )
+        return null
+    }
+}
+
+// Add a log transport from anywhere in mikser-io's lifecycle —
+// typically from a plugin's factory (the canonical Better Stack /
+// Datadog / Loki / Axiom / Sentry shape) or from a plugin's onLoaded
+// hook for deferred / runtime-resolved integrations.
+//
+// Behavior depends on when this is called:
+//
+//   - Before createMikserLogger() has run (factory phase during
+//     config.js's onLoad — plugin factories called inside the user's
+//     mikser.config.js evaluate here): the entry queues. The next
+//     createMikserLogger() call drains the queue.
+//
+//   - After createMikserLogger() has run (plugin onLoaded, any later
+//     hook, runtime injection): the new pino.transport stream is
+//     built and pushed onto the live multistream, then runtime.engine
+//     .logger is swapped to a fresh pino backed by the updated list.
+//     useLogger() reads runtime.engine.logger on each call, so all
+//     subsequent log emissions reach the new transport.
+//
+// Returns true when the transport was queued or successfully added,
+// false when transport stream construction failed (the load error
+// already went to stderr via buildTransportStream).
+export function addLogTransport(entry) {
+    if (currentStreams === null) {
+        pendingTransports.push(entry)
+        return true
+    }
+    const s = buildTransportStream(entry, currentLevel)
+    if (!s) return false
+    currentStreams.push(s)
+    if (runtime.engine) {
+        runtime.engine.logger = pino(
+            { level: 'trace', customLevels: CUSTOM_LEVELS },
+            pino.multistream(currentStreams),
+        )
+    }
+    return true
+}
+
 // Replace the bootstrap logger (built by engine.setup() with the
 // terminal-only stream) with one that includes any third-party
 // transports from runtime.config.logging.transports. Runs at onLoad
@@ -176,7 +261,9 @@ export function createMikserLogger(level = 'info') {
 // to closures that have already executed.
 onLoad(() => {
     if (!runtime.engine?.logger) return
-    if (!runtime.config?.logging?.transports?.length) return
+    const haveDeclared = (runtime.config?.logging?.transports?.length ?? 0) > 0
+    const havePending  = pendingTransports.length > 0
+    if (!haveDeclared && !havePending) return
     const level = runtime.engine.logger.level
     runtime.engine.logger = createMikserLogger(level)
 })