mikser-io 9.63.0 → 9.66.0

package/CLAUDE.md

@@ -233,6 +233,19 @@ brevity.
   - `{ name, options, postprocess, output?, setup?, teardown? }` →
     postprocessor descriptor; stored in `runtime.postprocessors`.
   Strings produce a v9 migration error pointing at the new shape.
+- `instance.js` — one engine per working folder. A second `mikser` in a
+  folder a watcher holds FORWARDS its build over a unix socket and wears
+  the instance's log output and exit code; `--no-attach` opts out and
+  warns. Socket lives in `os.tmpdir()` keyed by a hash of the resolved
+  working folder — NOT under `runtime/`, because sun_path caps a socket
+  path at ~107 bytes and a nested working folder fails as `listen
+  EINVAL`. chmod 0600, so the filesystem permission is the access
+  decision. A forwarded build RESCANS (`runtime.rebuild()`), never
+  drains: a client can beat the inotify event for the file it just
+  wrote. Exit code comes from `renderErrorCount()`, not
+  `process.exitCode` — the engine suppresses that in watch mode by
+  design. Config mismatch is refused by resolved PATH; config drift
+  under a running instance is detected by stat over `configCoverage`.
 - `manager.js` — file watching (chokidar) and cron scheduling. `watch()`
   turns file events into SYNC events — it is how a source folder becomes
   entities, so pointing it at the output folder feeds output back in as
@@ -423,6 +436,13 @@ Test coverage: `test/unit/source-sweep.test.js`.
   camelCase: `import { vector } from 'mikser-io-vector'`,
   `import { renderHbs } from 'mikser-io'`. Consumer uses
   `plugins: [vector({...})]` — never the bare string.
+- **Route paths**: a plugin mounts at `/<name>`, with a `base` or `path`
+  option to move it — api `/api`, auth `/auth`, drive `/drive`, forms
+  `/forms`, mcp `/mcp`, preview `/preview`, vector `/vector`, decap
+  `/admin`. The output folder is served from `/`, so a route CAN shadow a
+  page; the accepted answer is a predictable name plus a way to change
+  it, not a reserved prefix. Follow the eight, do not invent a ninth
+  shape.
 - **Tool names**: the registry (`src/tools.js`) holds BARE names —
   `explain`, `verify`, `sources`, `search`. The `mikser_` prefix is MCP's
   namespacing, because its tool names are flat across every connected

package/app.js

@@ -1,8 +1,56 @@
 #!/usr/bin/env node
-import { setup } from "./index.js"
+import path from 'node:path'
+
+import { setup } from './index.js'
+import { forward } from './src/instance.js'
+
+// Before anything is imported or read.
+//
+// A second `mikser` in a folder a watcher already holds used to start a second
+// engine: two writers, one catalogue, one output tree, no warning. It forwards
+// the request instead and wears the answer — which also means it never pays to
+// import the config or the plugin graph, most of what a one-shot spends.
+//
+// Only the flags that decide WHERE are parsed here. Everything else is the
+// running instance's business, and parsing it properly is what commander is
+// for once we know we are staying.
+function locate(argv) {
+    const value = (...names) => {
+        for (const name of names) {
+            const i = argv.indexOf(name)
+            if (i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('-')) return argv[i + 1]
+            const inline = argv.find(a => a.startsWith(`${name}=`))
+            if (inline) return inline.slice(name.length + 1)
+        }
+        return null
+    }
+    const has = (...names) => names.some(n => argv.includes(n))
+    return {
+        workingFolder: value('--working-folder', '-i') ?? '.',
+        config: value('--config', '-c') ?? 'mikser.config.js',
+        clear: has('--clear'),
+        // Commander's negated form: `attach` is true unless --no-attach said so.
+        attach: has('--no-attach') ? false : true,
+        // Report-only runs read; they do not write the catalogue or the output
+        // tree, and their handlers exit the process themselves. Left local —
+        // the guard in setup() still says an instance is there.
+        reportOnly: has('--tool', '--tools', '--verify', '--explain'),
+    }
+}
 
 async function main() {
+    const where = locate(process.argv.slice(2))
+    if (where.attach !== false && !where.reportOnly) {
+        const code = await forward({
+            workingFolder: path.resolve(where.workingFolder),
+            config: path.resolve(where.workingFolder, where.config),
+            clear: where.clear,
+        })
+        // null means nobody was listening — carry on exactly as before.
+        if (code !== null) process.exit(code)
+    }
+
     const mikser = await setup()
     await mikser.start()
 }
-main()
+main()

package/docs/diagnostics.md

@@ -27,6 +27,7 @@ engine source, the entry point is missing and belongs on this page.
 | Did my schema validate anything at all? | [`schemas.names()`](#schemasnames--schemaslookup) |
 | A tool answered emptily — is it broken, or is there nothing to find? | [`faults`](#faults) |
 | I edited the build and nothing rebuilt | `--json` → `config.files` |
+| Is another mikser already holding this folder? | run any command — it forwards, or says so |
 | Why did this build do any work at all? | `--json` → `invalidated` |
 | Did my new pattern get a chance to match? | `--json` → `evaluated` |
 
@@ -733,6 +734,36 @@ content is clean.
 get, stats, config }` — the on-demand render cache, useful for asking
 what has been rendered outside a build.
 
+## One engine per folder
+
+Running `mikser` while `mikser --watch` holds the same folder used to start a
+second engine: two writers over one catalogue and one output tree, with no lock
+and no warning. A `--clear` from either is what produces a cold rebuild that
+reports nothing rendered.
+
+A second invocation now forwards its build to the running instance and wears
+its answer — the instance's log output, the instance's exit code. Nothing to
+learn, and no question about *which* cycle covers your edit: you asked, so the
+answer is about your request. It is also faster, because a forwarded command
+never imports the config or the plugin graph, which is most of what a one-shot
+spends its time on.
+
+Three things it refuses or reports rather than guessing:
+
+- **A different config.** If you resolve `mikser.config.prod.js` and the
+  instance is running `mikser.config.js`, it refuses. Building with the wrong
+  config is the accident this exists to prevent.
+- **A config that moved under the instance.** It stats every file in
+  `config.files` and tells you to restart rather than building with a config
+  you have since edited.
+- **A folder held by someone else.** `--no-attach` runs a private engine
+  anyway — for checking that a cold start works — and says the folder is held.
+
+A forwarded build **rescans**; it does not drain what the watcher happened to
+queue. A client that writes a file and immediately asks can beat the file
+event, and draining would then build without the change that prompted the
+request.
+
 ## Faults
 
 A **fault** is a subsystem saying it cannot do its job — as opposed to an

package/docs/rendering.md

@@ -113,6 +113,24 @@ Inside a render, a `runtime` object is assembled and passed to all plugins:
 
 Render plugins extend this object further (e.g. `runtime.href`, `runtime.asset`, `runtime.resource`).
 
+`asset(preset, url)` returns the deployed URL of a preset derivative, relative
+to the page asking for it:
+
+```hbs
+<img src="{{ (asset 'web' '/media/hero.jpg').url }}">
+```
+
+The extension comes from the preset — every preset module exports a `format`,
+and the helper uses it, so a template never has to repeat it. Pass a third
+argument to override it, and mikser warns if that contradicts what the preset
+actually produces.
+
+It BUILDS the url rather than looking one up, which is worth knowing: nothing
+it returns has been checked against a file. A preset name nothing declares
+warns once, but a derivative that simply was not generated cannot be detected
+here. Where you have the entity rather than a path, `meta.presets` is the
+looked-up answer (ADR-0011).
+
 ### Logging from templates
 
 The runtime exposes five logger functions — `log` (info), `warn`, `error`, `debug`, `trace` — that route through Mikser's central logger (`useLogger()` is resolved at call time, so progress-bar wrappers in `info` mode are honoured). Each renderer's auto-helper loop picks them up:

package/index.js

@@ -15,6 +15,9 @@ export * from './src/lifecycle.js'
 // cache's constraints: main-thread only, so async, so knex, so portable to
 // another engine.
 export * from './src/database/durable.js'
+// One engine per working folder: the control socket a second invocation
+// forwards to, and the guard that says so when it cannot.
+export * from './src/instance.js'
 
 export * from './src/database/index.js'
 export * from './src/journal.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.63.0",
+  "version": "9.66.0",
   "description": "A mixer for content: entities in, configurable render pipelines, outputs of any kind. Static sites are the canonical recipe, not the definition — the same engine renders PDFs, emails and whatever a renderer plugin produces. Files are the source of truth, every lifecycle phase is observable, and the build graph is queryable by an agent.",
   "main": "index.js",
   "exports": {

package/src/engine.js

@@ -6,6 +6,7 @@ import _ from 'lodash'
 import Piscina from 'piscina'
 import runtime from './runtime.js'
 import { onInitialize, onInitialized, onLoad, onImport, onRender, onCancel, onCancelled, onFinalized, onLoaded, onBeforePostprocess, onPostprocess, postprocessEntities } from './lifecycle.js'
+import { instanceControl } from './instance.js'
 import { useJournal, updateEntry } from './journal.js'
 import { globby } from 'globby'
 import { OPERATION, TASKS } from './constants.js'
@@ -132,10 +133,16 @@ export async function setup(options) {
     // need an agent surface configured when `--verify` does not.
     registerBuiltinTools()
 
+    // One engine per working folder: publish the control socket when this
+    // process is long-running, and warn when a private one starts in a folder
+    // somebody else is already holding.
+    instanceControl()
+
     onInitialize(async () => {
         runtime.engine.commander?.version(packageInfo.version)
             .option('-i --working-folder <folder>', 'set mikser working folder', './')
             .option('-c --config <file>', 'set mikser mikser.config.js location', './mikser.config.js')
+            .option('--no-attach', 'start a private engine instead of forwarding to the one already running here')
             .option('-m --mode <mode>', 'set mikser runtime mode', 'development')
             .option('-r --clear', 'clear current state before execution', false)
             .option('-o --output-folder <folder>', 'set mikser output folder relative to working folder', 'out')

package/src/instance.js

@@ -0,0 +1,383 @@
+// One engine per working folder.
+//
+// Running `mikser` next to a live `mikser --watch` used to start a second
+// engine on the same folder: two writers, one sqlite catalogue, one output
+// tree, no lock and no warning. WAL keeps the pages intact and does nothing
+// for the logical state — a `--clear` from one process while the other holds
+// the folder produces a cold rebuild reporting nothing rendered, and output
+// that does not match source.
+//
+// The fix is not a lock alone, because a lock only forbids the thing people
+// were doing for a reason. A one-shot build is not faster than the watcher —
+// the watcher has usually already done the work — it is started because
+// PROCESS EXIT IS THE ONLY COMPLETION SIGNAL. Everything else in mikser
+// hot-reloads; nothing else says "the tree is settled, assert against it now".
+//
+// So a second invocation forwards its request to the running instance and
+// wears its result: the instance's log output, the instance's exit code. The
+// caller asked for a build and gets an answer about that build, with nothing
+// new to learn and no watermark to reason about — which matters, because a
+// design that needs discipline from the caller is the one that gets violated.
+//
+// `--no-attach` opts out, for when a fresh process IS the point: checking that
+// a cold start works, that startup ordering hides nothing. Named for what it
+// switches off rather than for a property of the process — the default is to
+// attach, and the flag should say which behaviour is being declined.
+
+import net from 'node:net'
+import { createHash } from 'node:crypto'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { existsSync, unlinkSync } from 'node:fs'
+import { chmod } from 'node:fs/promises'
+
+import runtime from './runtime.js'
+import { onLoaded } from './lifecycle.js'
+import { renderErrorCount } from './report.js'
+
+// Where the endpoint lives.
+//
+// A unix socket rather than a port: no allocation, no auth decision, no
+// network exposure. The obvious home is under the working folder, and it does
+// not work — sun_path caps a socket path at about 107 bytes, and a working
+// folder nested a few levels deep blows through that. It fails as
+// `listen EINVAL`, which is not a phrase that suggests "your path is long",
+// so it would have been diagnosed as forwarding simply not working.
+//
+// So: a short, fixed-length name in the system temp directory, derived from
+// the resolved working folder. One rule, no length to exceed, and it survives
+// an `rm -rf runtime`.
+//
+// The permissions argument survives the move. The socket is chmod 0600 after
+// listen, so it is the owner's alone — /tmp being world-writable buys an
+// attacker the ability to create their own socket, not to talk to this one.
+//
+// Windows has no unix sockets; Node maps this name shape onto a named pipe,
+// which has no such length limit.
+export function socketPath(workingFolder) {
+    const key = createHash('sha1').update(path.resolve(workingFolder ?? '.')).digest('hex').slice(0, 16)
+    return process.platform === 'win32'
+        ? `\\\\.\\pipe\\mikser-${key}`
+        : path.join(tmpdir(), `mikser-${key}.sock`)
+}
+
+// ── protocol ────────────────────────────────────────────────────────────
+//
+// Newline-delimited JSON, one object per line. Deliberately boring: both ends
+// ship together, so there is nothing to negotiate and no version to carry.
+//
+//   → { type: 'build', config, clear }
+//   ← { type: 'log', chunk }        (zero or more, in order)
+//   ← { type: 'done', code }
+//   ← { type: 'refused', reason, detail }
+
+function frame(socket, object) {
+    try { socket.write(JSON.stringify(object) + '\n') } catch { /* peer gone */ }
+}
+
+function readFrames(socket, onFrame) {
+    let buffer = ''
+    socket.on('data', (chunk) => {
+        buffer += chunk.toString()
+        let index
+        while ((index = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, index)
+            buffer = buffer.slice(index + 1)
+            if (!line.trim()) continue
+            try { onFrame(JSON.parse(line)) } catch { /* not ours */ }
+        }
+    })
+}
+
+// ── client ──────────────────────────────────────────────────────────────
+
+// Ask the running instance to build, and wear its answer.
+//
+// Returns the exit code to use, or null when there is nobody to ask — in
+// which case the caller proceeds exactly as it always did. Called before
+// setup(), so a forwarded command never pays for importing the config or the
+// plugin graph, which is most of what a one-shot spends its time on.
+export function forward({ workingFolder, config, clear }) {
+    const endpoint = socketPath(workingFolder)
+
+    return new Promise((resolve) => {
+        const socket = net.connect(endpoint)
+        let answered = false
+
+        // Nobody home. A crash leaves the socket file behind, so "connect
+        // failed" has to mean "no instance — clean up and carry on" rather
+        // than a hang: this is the way the pattern usually breaks.
+        socket.on('error', () => {
+            if (answered) return
+            answered = true
+            if (process.platform !== 'win32' && existsSync(endpoint)) {
+                try { unlinkSync(endpoint) } catch { /* another client won the race */ }
+            }
+            resolve(null)
+        })
+
+        socket.on('connect', () => frame(socket, { type: 'build', config, clear }))
+
+        readFrames(socket, (message) => {
+            if (message.type === 'log') {
+                // The instance's output for THIS request, on the stream it
+                // would have used locally.
+                process.stderr.write(message.chunk)
+            } else if (message.type === 'refused') {
+                answered = true
+                process.stderr.write(`mikser: ${message.reason}\n`)
+                if (message.detail) process.stderr.write(`${message.detail}\n`)
+                socket.end()
+                resolve(1)
+            } else if (message.type === 'done') {
+                answered = true
+                socket.end()
+                resolve(message.code ?? 0)
+            }
+        })
+
+        // The instance went away mid-request. Not "success with no output":
+        // the build this was asked about has no known outcome.
+        socket.on('close', () => {
+            if (answered) return
+            answered = true
+            process.stderr.write('mikser: the running instance closed the connection before finishing.\n')
+            resolve(1)
+        })
+    })
+}
+
+// ── server ──────────────────────────────────────────────────────────────
+
+// Requests run one at a time, to completion.
+//
+// Not because the engine could not interleave them, but because "which cycle
+// covers my edit" is the question this whole thing exists to remove. Serialised,
+// a client's answer is about a cycle that started after its request arrived,
+// and the log output during that window belongs to exactly one request.
+let chain = Promise.resolve()
+let server = null
+
+// Tee the process's own output to the client for the duration of its request.
+//
+// The engine logs through pino to stdout/stderr; capturing there rather than
+// adding a log transport means the client sees precisely what it would have
+// seen locally, formatting and all, with no second rendering of the same
+// records to keep in step.
+function captureOutput(onChunk) {
+    const originals = [process.stdout.write, process.stderr.write]
+    const patch = (stream, original) => function (chunk, encoding, callback) {
+        try { onChunk(typeof chunk === 'string' ? chunk : chunk.toString()) } catch { /* client gone */ }
+        return original.call(stream, chunk, encoding, callback)
+    }
+    process.stdout.write = patch(process.stdout, originals[0])
+    process.stderr.write = patch(process.stderr, originals[1])
+    return () => {
+        process.stdout.write = originals[0]
+        process.stderr.write = originals[1]
+    }
+}
+
+// Is the config the client resolved the one this instance is running?
+//
+// The accident this prevents is the one already written down: a command
+// resolving mikser.config.prod.js reaching an instance running the dev config
+// executes against the wrong one, silently. Compared by resolved PATH rather
+// than by content hash — the hash would require the client to import its
+// config, which is most of the startup forwarding exists to skip, and it is
+// not what tells the two apart. Different configs are different files.
+function configMismatch(theirs) {
+    if (!theirs) return null
+    const mine = path.resolve(runtime.options.config ?? 'mikser.config.js')
+    return path.resolve(theirs) === mine ? null : mine
+}
+
+// Has this instance's own config changed under it since it started?
+//
+// The other half of the same question, and the half a client cannot answer.
+// configCoverage lists every local module the config graph pulled in, so a
+// stat over that list catches an edit to an imported module — which a
+// client-side checksum of the entry file would miss entirely.
+async function configStale() {
+    const covered = runtime.options.configCoverage?.files ?? []
+    if (!covered.length) return null
+    const { stat } = await import('node:fs/promises')
+    const stamps = runtime.options.configStamps
+    if (!stamps) {
+        // First call: record, do not judge. Nothing to compare against yet.
+        runtime.options.configStamps = Object.fromEntries(
+            await Promise.all(covered.map(async (file) => {
+                try { return [file, (await stat(file)).mtimeMs] } catch { return [file, 0] }
+            })))
+        return null
+    }
+    for (const file of covered) {
+        let now = 0
+        try { now = (await stat(file)).mtimeMs } catch { /* deleted counts as changed */ }
+        if (stamps[file] !== now) return file
+    }
+    return null
+}
+
+async function serveBuild(socket, request, logger) {
+    const wrongConfig = configMismatch(request.config)
+    if (wrongConfig) {
+        frame(socket, {
+            type: 'refused',
+            reason: `this instance is running ${wrongConfig}, and you asked for ${path.resolve(request.config)}.`,
+            detail: 'Forwarding would build with the wrong config — the accident this refusal exists to prevent. '
+                + 'Stop that instance, or pass --no-attach to run your own.',
+        })
+        return
+    }
+
+    const movedFile = await configStale()
+    if (movedFile) {
+        frame(socket, {
+            type: 'refused',
+            reason: `this instance's config changed on disk since it started (${movedFile}).`,
+            detail: 'It is still building with the old one. Restart it, and this command will reach an '
+                + 'instance that matches what you edited.',
+        })
+        return
+    }
+
+    const restore = captureOutput((chunk) => frame(socket, { type: 'log', chunk }))
+    let code = 0
+    try {
+        // Fire the pending debounce rather than waiting it out.
+        //
+        // The 1000ms window exists to INFER that editing has stopped. A client
+        // asking for a build has STATED it, so inference is not needed and the
+        // timer is pure latency. The accumulated events are not discarded by
+        // this: the watcher already wrote them into the journal, so clearing
+        // the timer and building now covers exactly what it would have.
+        clearTimeout(runtime.engine?.processTimeout)
+
+        // RESCAN, not drain.
+        //
+        // A watch cycle processes what the watcher reported. A client that
+        // writes a file and immediately asks for a build can beat the inotify
+        // event, so draining what is already queued would build without the
+        // change that prompted the request — the watermark bug wearing a
+        // different hat. Rescanning makes a forwarded build mean what a
+        // one-shot means, which is what every existing caller assumes.
+        await runtime.rebuild()
+
+        // From the render-error count, NOT from process.exitCode.
+        //
+        // The engine deliberately leaves exitCode alone in watch mode — a
+        // failed render there is a state to fix on the next cycle, not a
+        // reason to tear the watcher down — and the instance is always in
+        // watch or server mode. So the signal a one-shot would have exited
+        // with does not exist here and has to be read from the report, which
+        // is where it came from in the first place.
+        code = renderErrorCount() ? 1 : 0
+    } catch (err) {
+        logger?.error('instance: forwarded build failed — %s', err.message)
+        code = 1
+    } finally {
+        restore()
+    }
+    frame(socket, { type: 'done', code })
+}
+
+// Listen, if this process is one that sticks around.
+//
+// A one-shot build has nothing to offer a client — it is already exiting — so
+// only a watcher or a server publishes an endpoint.
+export function serveInstance() {
+    onLoaded(async () => {
+        if (!runtime.options.watch && !runtime.options.server) return
+        if (runtime.options.attach === false) return
+        const logger = runtime.engine?.logger
+        const endpoint = socketPath(runtime.options.workingFolder)
+
+        // A socket left by a crash. Nothing is listening, so removing it is
+        // safe — and a live one would have refused this process's own startup
+        // long before here, in the client check.
+        if (process.platform !== 'win32' && existsSync(endpoint)) {
+            try { unlinkSync(endpoint) } catch { /* nothing to remove */ }
+        }
+        await configStale()   // record the baseline stamps
+
+        server = net.createServer((socket) => {
+            socket.on('error', () => { /* client vanished mid-request */ })
+            readFrames(socket, (request) => {
+                if (request.type !== 'build') return
+                chain = chain.then(() => serveBuild(socket, request, logger)).catch(() => {})
+            })
+        })
+        server.on('error', (err) => {
+            logger?.warn({ code: 'instance-listen-failed' },
+                'Could not open the control socket (%s). Other mikser commands in this folder will start their '
+                + 'own engine instead of talking to this one.', err.message)
+        })
+        server.listen(endpoint, async () => {
+            // The owner's, and nobody else's — the filesystem permission IS
+            // the access decision, which is why this needs no token.
+            if (process.platform !== 'win32') {
+                try { await chmod(endpoint, 0o600) } catch { /* best effort */ }
+            }
+            logger?.info('Instance socket: %s', endpoint)
+        })
+        server.unref?.()
+
+        const close = () => {
+            try { server?.close() } catch { /* already closed */ }
+            if (process.platform !== 'win32' && existsSync(endpoint)) {
+                try { unlinkSync(endpoint) } catch { /* gone */ }
+            }
+        }
+        process.on('exit', close)
+        for (const signal of ['SIGINT', 'SIGTERM']) {
+            process.on(signal, () => { close(); process.exit(0) })
+        }
+    })
+}
+
+// Say so when a private engine is starting in a folder someone else holds.
+//
+// The local counterpart of the rule already written down for deployments —
+// "never run a one-shot mikser command against the deployment" — which existed
+// because there was no alternative. There is one now, so this covers what is
+// left: --no-attach, and the report-only runs that stay local by design.
+//
+// A warning rather than a refusal. --no-attach is how you deliberately check
+// that a cold start works, and refusing it would take away the escape hatch
+// this design depends on having.
+export async function warnIfHeld({ workingFolder, attached }) {
+    const endpoint = socketPath(workingFolder)
+    if (process.platform !== 'win32' && !existsSync(endpoint)) return false
+
+    const live = await new Promise((resolve) => {
+        const probe = net.connect(endpoint)
+        const done = (answer) => { try { probe.destroy() } catch { /* already gone */ } resolve(answer) }
+        probe.on('connect', () => done(true))
+        probe.on('error', () => done(false))
+        setTimeout(() => done(false), 250).unref?.()
+    })
+    if (!live) return false
+
+    const logger = runtime.engine?.logger
+    const message = attached === false
+        ? 'Another mikser is already running in this folder, and --no-attach means this one will not talk to '
+          + 'it. Two engines share the catalogue and the output tree with no lock between them; a --clear from '
+          + 'either is what produces a cold rebuild that renders nothing.'
+        : 'Another mikser is already running in this folder. This command reads and does not write, so it is '
+          + 'safe — but it may see a catalogue mid-cycle.'
+    logger?.warn?.({ code: 'instance-already-running' }, message)
+    return true
+}
+
+// Registered at setup so both halves are wired from one call.
+export function instanceControl() {
+    serveInstance()
+    onLoaded(async () => {
+        if (runtime.options.watch || runtime.options.server) return
+        await warnIfHeld({
+            workingFolder: runtime.options.workingFolder,
+            attached: runtime.options.attach,
+        })
+    })
+}

package/src/plugins/render/asset.js

@@ -1,9 +1,61 @@
 import path from 'node:path'
 
-export function load({ runtime, entity, state, options }) {
+import { changeExtension } from '../../utils.js'
+
+// `{{asset 'web' '/media/hero.jpg'}}` — the deployed URL of a preset
+// derivative, relative to the page asking for it.
+//
+// It BUILDS the URL rather than looking one up, which is the source of every
+// way it used to go wrong: nothing it returns has been checked against
+// anything, so a mistake produces a perfectly well-formed link to a file that
+// does not exist. The page renders, the build is green, and the image is
+// missing — noticed by a person, later.
+//
+// Three of those are closed here. The remaining one is structural: the
+// derivative may simply not have been generated, and this cannot tell.
+// `meta.presets` (ADR-0011) is the looked-up answer where a caller has the
+// entity; this helper exists for the case where they have a path.
+export function load({ runtime, entity, state, options, logger }) {
+    const presets = state?.assets?.presets ?? {}
+    const warned = new Set()
+    const warnOnce = (key, code, message, ...args) => {
+        if (warned.has(key)) return
+        warned.add(key)
+        logger?.warn?.({ code }, message, ...args)
+    }
+
     runtime.asset = (preset, url, format) => {
         if (url[0] != '/') url = `/${url}`
-        const relative = `${state.assets.assetsFolder}/${preset}${format ? url.split('.').slice(0, -1).concat(format).join('.') : url}`
+
+        const declared = presets[preset]?.format
+
+        // A preset name nothing declares. The URL still gets built — it is a
+        // string operation and cannot fail — so without this a typo is a
+        // missing image and no other symptom anywhere.
+        if (!presets[preset]) {
+            warnOnce(`preset:${preset}`, 'asset-unknown-preset',
+                'asset() was asked for preset %j, which is not configured. The URL it returns points at a '
+                + 'derivative nothing generates. Configured: %s',
+                preset, Object.keys(presets).sort().join(', ') || '(none)')
+        }
+
+        // The format the preset itself declares, unless the caller overrode
+        // it. Every preset module exports one, so requiring the template to
+        // repeat it made the extension a thing two places had to agree about
+        // — and when they disagreed the link was wrong with nothing said.
+        const effective = format ?? declared
+
+        if (format && declared && format !== declared) {
+            warnOnce(`format:${preset}:${format}`, 'asset-format-mismatch',
+                'asset() was given format %j for preset %j, which produces %j. One of the two is wrong and '
+                + 'the URL follows the argument.', format, preset, declared)
+        }
+
+        // changeExtension, not a local split-and-rejoin. The inline version
+        // returned "webp" for a source with no extension — dropping the path
+        // and yielding a relative URL that resolves against whatever page
+        // happened to be rendering.
+        const relative = `${state.assets.assetsFolder}/${preset}${effective ? changeExtension(url, effective) : url}`
         const destination = '/' + relative
         const from = path.dirname(entity.destination || '/')
         return { url: path.relative(from, destination) }

package/src/report.js

@@ -117,6 +117,11 @@ export function resetReport() {
     runtime.state.changed = { ids: [], count: 0 }
 }
 
+// Published on the runtime so runtime.js can start a fresh cycle for a
+// forwarded build without importing this module — runtime.js loads first, and
+// an import here would close the cycle.
+runtime.resetReport = resetReport
+
 // End of a cycle: stamp it, file it, and wake anyone waiting on it.
 export function finishCycle() {
     if (!runtime.state?.cycle || runtime.state.cycle.finishedAt) return

package/src/routes.js

@@ -79,6 +79,21 @@ export function routeLocation(displayPath) {
 //   authLabel     bracketed reachability text override for the log.
 //
 // Returns the recorded descriptor.
+// WHERE a plugin mounts: `/<name>`, overridable.
+//
+// Not a new rule — the one every plugin already follows. api at /api, auth at
+// /auth, drive at /drive, forms at /forms, mcp at /mcp, preview at /preview,
+// vector at /vector, decap at /admin. Each takes a `base` or `path` option so
+// a project whose content wants that path can move it.
+//
+// The output folder is served from `/`, so a plugin route can shadow a page.
+// That is a real cost and this is the accepted answer to it: a predictable
+// name, and a way to change it. A reserved prefix like `/$name` would make
+// the collision impossible, and would also make this plugin the only one
+// shaped differently from the other eight — which is a worse trade than the
+// collision it avoids, because the collision is rare and visible and the
+// inconsistency is permanent.
+//
 export function registerRoute({
     path,
     plugin,

package/src/runtime.js

@@ -111,6 +111,25 @@ const runtime = {
         if (!this.options?.watch && !this.options?.server) await this.closeDurable?.()
     },
 
+    // A build on request, from a process that is already running.
+    //
+    // start() runs the import hooks once and every cycle after that only
+    // processes what the watcher reported. A forwarded build has to RESCAN:
+    // a client that writes a file and immediately asks can beat the inotify
+    // event, and draining the queue would then build without the change that
+    // prompted the request. Scanning makes it mean what a one-shot means.
+    //
+    // The gate makes the rescan cheap — an unchanged file is a checksum
+    // comparison, not a re-import.
+    async rebuild() {
+        // Its own cycle in the report, like any other — otherwise a forwarded
+        // build's counts are added to whatever the watcher last did.
+        this.resetReport?.()
+        await this.callHooks(this.hooks.import, undefined, 'import')
+        await this.callHooks(this.hooks.imported, undefined, 'imported')
+        await this.process()
+    },
+
     async process() {
         if (this.abortController?.signal.aborted) return
         else if (this.abortController) {