mikser-io 10.13.0 → 11.0.1

package/docs/api-reference.md

@@ -495,7 +495,8 @@ Query types throughout: function, lodash match object, or `undefined` for all.
 
 `updateEntity` is a catalog operation. `writeEntitySource` writes the FILE, with
 the checks that make a whole-file rewrite safe to perform without having watched
-the file the whole time.
+the file the whole time. `editEntitySource` changes PART of a file, by naming
+the text to change rather than resending the rest of it.
 
 ### `writeEntitySource(options)`
 
@@ -581,6 +582,52 @@ exactly the one that needs telling.
 
 `siblingDestinations(folder, relativePath)` reports files differing only by
 extension, which may render to the same destination.
+### `editEntitySource(options)`
+
+```js
+import { editEntitySource } from 'mikser-io'
+
+const result = await editEntitySource({
+    id: '/documents/pricing.md',
+    find: 'price: 1200',
+    replace: 'price: 1400',
+})
+```
+
+| Option | Meaning |
+| --- | --- |
+| `id` or `collection` + `relativePath` | Which file. Same rules as `writeEntitySource`. |
+| `find` | The exact text to replace. Must appear EXACTLY ONCE unless `all`. |
+| `replace` | What to put there. Empty or omitted deletes the matched text. |
+| `all` | Replace every occurrence instead of refusing an ambiguous anchor. Reports `replacements`. |
+| `ifChecksum`, `dryRun`, `awaitCycle`, `changeSet`, `summary`, `principal` | As `writeEntitySource`. |
+
+It is layered ON `writeEntitySource` rather than beside it, so containment, the
+change set, the cycle id, sibling destinations and the collection write
+capability are the same code path every other write goes through — a second
+implementation of any of those is a second implementation that can drift.
+
+**Why an anchor rather than a whole file.** A model rewriting a file to change
+one line must re-emit every other line, and a line it drops on the way is
+indistinguishable downstream from a line someone deleted on purpose.
+`ifChecksum` catches a stale READ; nothing catches a lossy WRITE. An anchor
+cannot lose what it does not name: the bytes outside the match are not merely
+preserved, they are never rewritten. That also makes the concurrency question
+sharper than a checksum — a checksum refuses when ANY part of the file moved,
+an anchor refuses when the part being edited moved.
+
+Its own refusals, on top of `writeEntitySource`'s: `no-anchor` (empty `find`),
+`anchor-not-found`, `anchor-ambiguous` (carrying `occurrences`), `no-such-file`
+(an edit changes something that exists; use the whole-file write to create),
+and `would-not-parse` (carrying the parser's complaint). The last one is the
+guarantee a whole-file write cannot make: the result is checked against the
+file's registered source format — see `validateSource` — and a file that would
+not parse never lands.
+
+Between reading the file and writing it back, the checksum it read is forwarded
+as the write's precondition, so a writer landing in that window is refused
+rather than overwritten.
+
 `locateEntityFile(id)` resolves a catalog id to its `{ collection, relativePath }`,
 or `{ error }` — taken from the entity rather than by splitting the id, since the
 prefix is configurable and the extension may have been stripped.

package/docs/plugins.md

@@ -28,7 +28,7 @@ Plugins are standard ESM imports. There's no name-based search path — whatever
 - Sibling plugins each export a named factory: `import { vector } from 'mikser-io-vector'`.
 - Project-local plugins live anywhere — drop the file, import by relative path: `import myPlugin from './plugins/my-plugin.js'`.
 
-Renderer and postprocessor packages **are** listed in `plugins: []` alongside lifecycle plugins. They return descriptors (`{ name, options, load?, render? }` or `{ name, options, postprocess, ... }`) instead of `(core) => void` closures; the loader stores them in `runtime.renderers` / `runtime.postprocessors` and the dispatcher picks them up by name when a layout requests them.
+Renderer and postprocessor packages **are** listed in `plugins: []` alongside lifecycle plugins. They return descriptors (`{ name, options, load?, render? }` or `{ name, options, postprocess, ... }`) instead of `(core) => void` closures; the loader stores them in `runtime.renderers` / `runtime.postprocessors` and the dispatcher picks them up by name when a layout requests them. If your package is **not** named `mikser-io-render-<name>` / `mikser-io-post-<name>`, add `module: import.meta.url` to the descriptor — a worker has no registry to read and otherwise resolves the name to a package that does not exist. See [rendering.md](rendering.md#declare-module-if-your-package-is-not-named-for-your-plugin).
 
 ---
 

package/docs/rendering.md

@@ -174,6 +174,37 @@ export async function render({ entity, options, config, context, plugins, runtim
 
 Only the renderer plugin (named `render-{options.renderer}`) is expected to export `render()`. Other plugins (loaded via `context.plugins`, `entity.meta.plugins`, `options.plugins`) typically only export `load()`.
 
+### Declare `module` if your package is not named for your plugin
+
+On the main thread a plugin is found in the runtime registry, under the `name`
+its descriptor carries. A **worker** is another thread with another runtime
+singleton, so its registry is empty and it resolves by name instead: plugin
+`render-preset` is looked for in a package called `mikser-io-render-preset`.
+
+That guess is right whenever the package is named for the plugin. It is wrong
+whenever one package ships a plugin under some other name — and then the
+failure is asymmetric, which is what makes it expensive: the main thread works,
+and only entities dispatched with `task: worker` break. A missing helper throws
+`Missing helper: "..."` and the page is never written; a missing renderer is a
+render fault naming the renderer.
+
+A descriptor can say where it lives:
+
+```js
+export function renderPreset(options = {}) {
+    return { name: options.name ?? 'preset', options, load, render, module: import.meta.url }
+}
+```
+
+`import.meta.url` and not the package name, because it points at the file that
+exports `load` / `render` at module level — which is what the worker imports —
+so nothing has to be re-exported from the package index to make it reachable.
+
+The field is optional and only consulted on a worker. A package named
+`mikser-io-render-<name>` or `mikser-io-post-<name>` needs nothing. Everything
+else should declare it; `mikser-io-assets` ships two such plugins (`preset` and
+`asset`) and declares both.
+
 ---
 
 ## Renderer Plugins

package/index.js

@@ -3,6 +3,7 @@ export * as constants from './src/constants.js'
 export * from './src/utils/index.js'
 export * from './src/invalidation.js'
 export * from './src/auth.js'
+export * from './src/principal.js'
 export * from './src/roles.js'
 export * from './src/inventory.js'
 export * from './src/report.js'

package/package.json

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

package/src/auth.js

@@ -1,5 +1,7 @@
 import crypto from 'node:crypto'
 import { isLoopback } from './utils/index.js'
+import { currentPrincipal } from './principal.js'
+import runtime from './runtime.js'
 
 // Authentication seam (ADR-0012).
 //
@@ -286,6 +288,66 @@ export function anyOf(...verifiers) {
 // four — the same partial answer, one layer down.
 export const CAPABILITY_WILDCARD = '*'
 
+// Writing to a collection is scoped to that collection.
+//
+//   write:<collection>     may change what is in it
+//
+// One name, asked by every write surface, so `write:documents` means the same
+// thing whether the write arrives over MCP, over the api, or from a plugin.
+// Reads are not scoped here: the api bounds them with `api:list` and the drive
+// with `drive:<endpoint>`, and inventing a third read rule would give three
+// answers to one question.
+export const writeCapabilityFor = (collection) => `write:${collection}`
+
+// Off until an operator turns it on, and turned on by granting.
+//
+// Enforcing immediately would refuse every write on every deployment that
+// exists, since nobody holds a capability that did not exist until now. So
+// the rule is the one the rest of this file already uses for principals,
+// applied to the catalogue: a site that declares no `write:` capability is
+// not using collection scoping, and its writes are bounded by whatever
+// bounded them before. The first `write:` grant turns it on for EVERY
+// collection at once — which is surprising exactly once, and is the only
+// reading that does not leave a half-enforced site.
+function collectionScopingConfigured(catalogue) {
+    return Object.values(catalogue ?? {}).flat()
+        .some(capability => String(capability).startsWith('write:'))
+}
+
+// The capability missing to write to this collection, or null when the write
+// may proceed. `catalogue` says whether the site uses collection scoping at
+// all; `principal` defaults to whoever the surface established.
+export function missingCollectionWrite(collection, {
+    principal = currentPrincipal(),
+    catalogue = runtime.options?.roles?.catalogue,
+} = {}) {
+    if (!collection) return null
+    if (!collectionScopingConfigured(catalogue)) return null
+    return missingCapability(principal, writeCapabilityFor(collection))
+}
+
+// Which of these capabilities the principal does NOT hold — the first one, or
+// null when it holds them all.
+//
+// The plural is the point. Almost every gate in the tree needs a SET, not one:
+// writing to a drive endpoint needs `drive:<name>` to reach it and
+// `drive:<name>:write` to change it, and "may ALSO write" means the base is a
+// prerequisite rather than an alternative. Each surface worked that out for
+// itself and they disagreed — the WebDAV mount required both, the tool over
+// the same endpoint required only the second, so one grant was refused a PUT
+// and allowed the identical write through the other door.
+//
+// Returning the MISSING capability rather than a boolean is what lets a
+// refusal name the one that is actually absent, which is the difference
+// between "you lack drive:documents" and "you lack drive:documents:write" when
+// the operator granted exactly one of them.
+export function missingCapability(principal, capabilities = []) {
+    for (const capability of [].concat(capabilities)) {
+        if (!hasCapability(principal, capability)) return capability
+    }
+    return null
+}
+
 export function hasCapability(principal, capability) {
     if (!capability) return true
     const caps = principal?.capabilities

package/src/engine/workers.js

@@ -16,8 +16,38 @@ export function workerMessages() {
     }
 }
 
+// The identifier a descriptor is known by once its closures are gone.
+// Render-shaped first, exactly as before: a descriptor carrying both `load`
+// and `postprocess` has always been treated as a renderer.
+function pluginIdentifier(plugin) {
+    if (!plugin || typeof plugin !== 'object' || typeof plugin.name !== 'string') return null
+    if (typeof plugin.load === 'function' || typeof plugin.render === 'function') return `render-${plugin.name}`
+    if (typeof plugin.postprocess === 'function') return `post-${plugin.name}`
+    return null
+}
+
 export function workerSafeOptions(opts) {
     const result = {}
+    // Where the code behind each identifier actually lives.
+    //
+    // The projection below reduces a descriptor to `render-<name>`, and the
+    // worker resolves that name BY CONVENTION: a package called
+    // `mikser-io-render-<name>`, or a file core ships. That convention is the
+    // whole resolution story on a worker, because the runtime registry the
+    // main thread reads is empty in another thread.
+    //
+    // So a renderer shipped under a package that is not named for it is
+    // unresolvable there — and the failure is asymmetric in the worst way:
+    // the main thread renders it fine from the registry, and only the
+    // worker-dispatched entities break. mikser-io-assets ships two such
+    // plugins (`preset` and `asset`), which is how 10.12.0 left every
+    // worker render that calls `asset()` failing on a missing helper.
+    //
+    // A descriptor that carries `module` — the `import.meta.url` of the file
+    // defining it — says where it is, and a string is exactly what survives
+    // the thread boundary. Optional: a package named by the convention needs
+    // nothing, so no existing plugin changes.
+    const pluginModules = {}
     for (const [k, v] of Object.entries(opts)) {
         // `plugins` is a mixed array of factory-return values — functions
         // (lifecycle plugins; workers don't need them) and descriptor
@@ -28,11 +58,9 @@ export function workerSafeOptions(opts) {
         if (k === 'plugins' && Array.isArray(v)) {
             result[k] = v
                 .map(p => {
-                    if (p && typeof p === 'object' && typeof p.name === 'string'
-                        && (typeof p.load === 'function' || typeof p.render === 'function'))   return `render-${p.name}`
-                    if (p && typeof p === 'object' && typeof p.name === 'string'
-                        && typeof p.postprocess === 'function')                                return `post-${p.name}`
-                    return null
+                    const identifier = pluginIdentifier(p)
+                    if (identifier && typeof p.module === 'string') pluginModules[identifier] = p.module
+                    return identifier
                 })
                 .filter(Boolean)
             continue
@@ -42,5 +70,8 @@ export function workerSafeOptions(opts) {
             result[k] = v
         } catch { /* not cloneable — skip */ }
     }
+    // Only when something declared one, so an options object a test compares
+    // whole does not grow an empty key.
+    if (Object.keys(pluginModules).length) result.pluginModules = pluginModules
     return result
 }

package/src/inventory.js

@@ -30,39 +30,29 @@ function repositoryUrl(repository) {
         .replace(/\.git$/, '')
 }
 
-// Which plugins are actually RUNNING, as opposed to merely installed.
+// Every mikser package INSTALLED beside this one, described.
 //
-// The distinction is the useful half: a package in node_modules that no config
-// loads explains nothing about the site's behaviour, and an agent told
-// otherwise will look for a feature that is not switched on.
-function activeNames() {
-    const active = new Set()
-    const named = (short) => (short.startsWith('mikser-io') ? short : `mikser-io-${short}`)
-
-    // Every plugin that mounts a route already names itself there — the
-    // strongest signal available, and one that stays correct as plugins are
-    // added, because registerRoute requires it.
-    for (const route of runtime.routes ?? []) {
-        if (route?.plugin) active.add(named(route.plugin))
-    }
-    // Renderers and postprocessors are registered by name rather than by
-    // package, and the package name is that name in a fixed shape.
-    for (const name of runtime.renderers?.keys() ?? []) active.add(`mikser-io-render-${name}`)
-    for (const name of runtime.postprocessors?.keys() ?? []) active.add(`mikser-io-post-${name}`)
-    // A lifecycle plugin that mounts nothing is recognised by the surface it
-    // publishes on the runtime.
-    if (runtime.options?.layouts) active.add('mikser-io-layouts')
-    if (runtime.options?.preview) active.add('mikser-io-preview')
-    // The engine itself is always running; saying otherwise would be odd.
-    active.add('mikser-io')
-    return active
-}
-
-// Every mikser package installed beside this one, described.
+// Installed, and nothing more. This list used to carry an `active` flag,
+// derived by probing whatever surfaces a plugin happened to expose — a route
+// here, a CLI flag there. Two things were wrong with it and only the second
+// was dangerous.
+//
+// The probe went stale silently: it tested `runtime.options.layouts`, which
+// stopped being layouts' API object two majors ago and is now the `--layouts`
+// folder flag, so layouts read as inactive on every site that did not pass a
+// flag it has no reason to pass. It also tested `runtime.options.preview` for
+// a package, `mikser-io-preview`, that does not exist.
+//
+// And the flag was three-valued in code and two-valued in its contract:
+// present meant running, absent meant EITHER not running or not detectable,
+// and an agent told to read it "to know what the system can do" could only
+// read absence as off. On a real site that said no schema validation and no
+// git sync while both were running — and git sync is the only route by which
+// an agent's own edit reaches the repository.
 //
-// `active` is reported only where it can be established: a lifecycle plugin
-// that publishes nothing on the runtime cannot be detected, and saying `false`
-// for it would be a claim rather than an absence of one.
+// What is running is now answered by the runtime recording what it loads, in
+// plugins.js. This answers a different and still useful question: what is on
+// disk, what version, and where to read about it.
 export function inventory({ workingFolder = runtime.options?.workingFolder } = {}) {
     const root = path.join(workingFolder ?? '.', 'node_modules')
     let names = []
@@ -72,7 +62,6 @@ export function inventory({ workingFolder = runtime.options?.workingFolder } = {
         return []
     }
 
-    const active = activeNames()
     const plugins = []
     for (const name of names.sort()) {
         try {
@@ -82,7 +71,6 @@ export function inventory({ workingFolder = runtime.options?.workingFolder } = {
                 name,
                 version: manifest.version ?? null,
                 ...(manifest.description ? { summary: manifest.description } : {}),
-                ...(active.has(name) ? { active: true } : {}),
                 ...(manifest.homepage ? { homepage: manifest.homepage } : {}),
                 ...(repository ? { repository } : {}),
                 npm: `https://www.npmjs.com/package/${name}`,
@@ -91,3 +79,25 @@ export function inventory({ workingFolder = runtime.options?.workingFolder } = {
     }
     return plugins
 }
+
+// What this runtime LOADED — the answer to "what is running".
+//
+// Read from the record plugins.js keeps as it loads, not derived from
+// surfaces afterwards. Every loaded plugin appears, including one that named
+// nothing: `package: null` means "running, and did not say what it is", which
+// is a different statement from not running and must never be collapsed into
+// one. Nothing here is ever absent because it could not be detected — a plugin
+// that is loaded is in this list.
+export function loadedPlugins({ workingFolder = runtime.options?.workingFolder } = {}) {
+    const root = path.join(workingFolder ?? '.', 'node_modules')
+    const versionOf = (name) => {
+        if (!name) return null
+        try {
+            return JSON.parse(readFileSync(path.join(root, name, 'package.json'), 'utf8')).version ?? null
+        } catch { return null }
+    }
+    return (runtime.plugins ?? []).map(entry => ({
+        ...entry,
+        ...(entry.package ? { version: versionOf(entry.package) } : {}),
+    }))
+}

package/src/plugins/api.js

@@ -1209,5 +1209,10 @@ export function api(options = {}) {
             }
         }
     })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/commands.js

@@ -304,6 +304,6 @@ export function commands(options = {}) {
             reportUnfired()
         })
 
-        return { executeCommand }
+        return { executeCommand, module: import.meta.url }
     }
 }

package/src/plugins/data.js

@@ -216,5 +216,10 @@ export function data(options = {}) {
             }
         }
     })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/documents.js

@@ -29,6 +29,6 @@ export function documents(options = {}) {
             phase: 'import',
         })
 
-        return { collection, type }
+        return { collection, type, module: import.meta.url }
     }
 }

package/src/plugins/files.js

@@ -273,6 +273,7 @@ export function files(options = {}) {
         return {
             collection,
             type,
+            module: import.meta.url,
         }
     }
 }

package/src/plugins/front-matter.js

@@ -20,5 +20,10 @@ export function frontMatter(options = {}) {
                 }
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/json.js

@@ -16,5 +16,10 @@ export function json(options = {}) {
                 }
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/mapper.js

@@ -22,5 +22,10 @@ export function mapper(options = {}) {
                 }
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/observer.js

@@ -212,6 +212,7 @@ export function observer(options = {}) {
 
         return {
             format,
+            module: import.meta.url,
         }
     }
 }

package/src/plugins/render/file.js

@@ -164,5 +164,5 @@ export function load({ runtime, options, track, logger }) {
 }
 
 export function fileHelpers(options = {}) {
-    return { name: options.name ?? 'file', options, load }
+    return { name: options.name ?? 'file', options, load, module: import.meta.url }
 }

package/src/plugins/render/hbs.js

@@ -327,5 +327,6 @@ export function renderHbs(options = {}) {
         load,
         render,
         parseReferences,
+        module: import.meta.url,
     }
 }

package/src/plugins/render/href.js

@@ -41,5 +41,5 @@ export function load({ entity, runtime, options }) {
 }
 
 export function hrefUrlHelpers(options = {}) {
-    return { name: options.name ?? 'href', options, load }
+    return { name: options.name ?? 'href', options, load, module: import.meta.url }
 }

package/src/plugins/render/resource.js

@@ -24,5 +24,5 @@ export function load({ runtime, entity, state, options, track }) {
 }
 
 export function resourceUrlHelper(options = {}) {
-    return { name: options.name ?? 'resource', options, load }
+    return { name: options.name ?? 'resource', options, load, module: import.meta.url }
 }

package/src/plugins/resources.js

@@ -245,6 +245,7 @@ export function resources(options = {}) {
         return {
             collection,
             type,
+            module: import.meta.url,
         }
     }
 }

package/src/plugins/shares.js

@@ -38,5 +38,10 @@ export function shares(options = {}) {
                 }
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/validator.js

@@ -14,5 +14,10 @@ export function validator(options = {}) {
                 })
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins/yaml.js

@@ -22,5 +22,10 @@ export function yaml(options = {}) {
                 }
             }
         })
+
+        // Names this package to the runtime's loaded-plugin record — see
+        // plugins.js. A plugin that declares nothing still reports as loaded,
+        // but as `package: null`.
+        return { module: import.meta.url }
     }
 }

package/src/plugins.js

@@ -1,6 +1,9 @@
 import { useLogger } from './engine/index.js'
 import { onLoad } from './lifecycle.js'
 import { resetServices } from './services.js'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { existsSync, readFileSync } from 'node:fs'
 import runtime from './runtime.js'
 
 import * as core from '../index.js'
@@ -40,6 +43,9 @@ onLoad(() => {
     // always sees a Map, never undefined.
     runtime.renderers      = runtime.renderers      ?? new Map()
     runtime.postprocessors = runtime.postprocessors ?? new Map()
+    // Rebuilt, not appended to: loadPlugins runs again on a config change, and
+    // a list that accumulated would report every plugin twice.
+    runtime.plugins = []
 
     const factoryEntries = []
     let registeredRenderers = 0
@@ -62,6 +68,8 @@ onLoad(() => {
                     continue
                 }
                 runtime.renderers.set(name, entry)
+                recordPlugin({ kind: 'renderer', name,
+                               package: packageOfModule(entry.module), module: entry.module ?? null })
                 registeredRenderers++
                 continue
             }
@@ -72,6 +80,8 @@ onLoad(() => {
                     continue
                 }
                 runtime.postprocessors.set(name, entry)
+                recordPlugin({ kind: 'postprocessor', name,
+                               package: packageOfModule(entry.module), module: entry.module ?? null })
                 registeredPostprocessors++
                 continue
             }
@@ -140,17 +150,83 @@ onLoad(() => {
             logger.error('Plugin factory threw on registration: %s', err.message)
             continue
         }
-        const label = descriptor?.collection ?? descriptor?.type ?? `plugin-${index + 1}`
+        // `plugin-7` names nothing a reader can act on. A plugin that
+        // declared its module has already said where it is, so the file's own
+        // stem is a better name than its position in an array.
+        const declaredName = descriptor?.module
+            ? path.basename(String(descriptor.module).split('?')[0]).replace(/\.[cm]?js$/, '')
+            : null
+        const label = descriptor?.collection ?? descriptor?.type ?? declaredName ?? `plugin-${index + 1}`
+        const registered = []
         for (const name of hookNames) {
-            for (const hook of runtime.hooks[name].slice(before.get(name))) {
+            const added = runtime.hooks[name].slice(before.get(name))
+            if (added.length) registered.push(name)
+            for (const hook of added) {
                 // A plugin registering the same function twice keeps its first
                 // label rather than being renamed by a later registration.
                 if (typeof hook === 'function' && !hook.mikserPlugin) hook.mikserPlugin = label
             }
         }
+        // Recorded whether or not it named itself. A plugin that declares
+        // nothing is still loaded, and the list must say so — that is the
+        // whole difference between this and the probe it replaces.
+        recordPlugin({
+            kind: 'lifecycle',
+            label,
+            package: packageOfModule(descriptor?.module),
+            module: descriptor?.module ?? null,
+            ...(descriptor?.collection ? { collection: descriptor.collection } : {}),
+            hooks: registered,
+        })
     }
 })
 
+
+// The package a module belongs to, read from the nearest package.json.
+//
+// Walked up from the file rather than pattern-matched on the path: a plugin
+// developed in a workspace sits at `~/Projects/mikser/mikser-io-git`, and the
+// same plugin installed sits at `<site>/node_modules/mikser-io-git`. Only the
+// manifest is true in both, and only the manifest is true for a plugin whose
+// package is not named for it.
+function packageOfModule(moduleUrl) {
+    if (typeof moduleUrl !== 'string') return null
+    let dir
+    try {
+        dir = path.dirname(moduleUrl.startsWith('file:') ? fileURLToPath(moduleUrl) : moduleUrl)
+    } catch { return null }
+    for (let depth = 0; depth < 12; depth++) {
+        const manifest = path.join(dir, 'package.json')
+        if (existsSync(manifest)) {
+            try { return JSON.parse(readFileSync(manifest, 'utf8')).name ?? null } catch { return null }
+        }
+        const parent = path.dirname(dir)
+        if (parent === dir) break
+        dir = parent
+    }
+    return null
+}
+
+// What this runtime LOADED, recorded as it loads it.
+//
+// Not derived afterwards. The previous answer was assembled by inventory.js
+// from whatever surfaces happened to be observable — a route here, a CLI flag
+// there — which made "is this plugin running" a question about how well the
+// probe was maintained rather than about the plugin. It reported layouts as
+// not running on every site that did not pass `--layouts`, because the flag it
+// probed had stopped being an API object two majors earlier and nothing failed
+// when it went stale.
+//
+// A plugin names itself by returning `module: import.meta.url` from its
+// factory, the same self-naming `registerRoute` and `provideService` already
+// require. One that names nothing is still recorded and still reported as
+// LOADED — its `package` is null, which says "this is running and did not say
+// what it is", never "this is not running".
+function recordPlugin(entry) {
+    runtime.plugins = runtime.plugins ?? []
+    runtime.plugins.push(entry)
+}
+
 function kebabToCamel(s) {
     return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
 }

package/src/postprocess.js

@@ -7,7 +7,7 @@ import _ from 'lodash'
 import { useLogger } from './engine/index.js'
 import engineRuntime from './runtime.js'
 
-export async function loadPlugin(pluginName, workingFolder, loggerOverride) {
+export async function loadPlugin(pluginName, workingFolder, loggerOverride, pluginModules) {
     // Worker contexts don't have access to the engine's pino instance
     // via useLogger() — callers from inside the Piscina dispatch pass
     // their port-forwarded logger explicitly so plugin-load failures
@@ -28,6 +28,9 @@ export async function loadPlugin(pluginName, workingFolder, loggerOverride) {
     } catch { /* package not installed at this level — fine, try next */ }
 
     const resolveLocations = [
+        // See render.js: what the descriptor declared, before anything that
+        // guesses a package name from the plugin name.
+        pluginModules?.[pluginName],
         path.join(workingFolder, 'node_modules', `mikser-io-${pluginName}/index.js`),
         nodeModulesResolved,
         path.join(workingFolder, 'plugins', `${pluginName}.js`),
@@ -110,7 +113,7 @@ export default async ({ entity, options, config, context, state, logger, port })
         .filter(p => p && p.indexOf('post-') == 0))
 
     for (let pluginName of pluginsToLoad) {
-        const plugin = await loadPlugin(pluginName, options.workingFolder, logger)
+        const plugin = await loadPlugin(pluginName, options.workingFolder, logger, options.pluginModules)
         if (!plugin) continue
         plugins[pluginName] = plugin
     }

package/src/principal.js

@@ -0,0 +1,33 @@
+// Who is acting, for the length of one request.
+//
+// A leaf, and an AsyncLocalStorage for the same reason changeSetContext is
+// one: the surfaces that KNOW the caller (an HTTP route, an MCP session) are
+// nowhere near the primitives that need to ask about them, and threading a
+// principal through every intervening call is how one of them comes to be
+// missed.
+//
+// This exists because the thing already flowing to the write primitives was
+// not an identity. `writeEntitySource` takes a `principal`, and what MCP puts
+// there is a display string — "dk@almero.bg (admins)" — built for the
+// change-set log. Asked `hasCapability(thatString, 'write:documents')` it
+// reads `undefined.capabilities`, takes the "not capability-scoped" branch,
+// and returns TRUE. An authorization check against it would not merely fail
+// to protect anything; it would look like protection while allowing
+// everything.
+//
+// `null` when nothing established a context, and that means UNKNOWN rather
+// than "nobody". Callers decide what unknown implies — the write gate treats
+// it the way it treats a credential that carries no capabilities, which is
+// how every static token and library caller already behaves.
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+const principalContext = new AsyncLocalStorage()
+
+export function withPrincipal(principal, fn) {
+    if (!principal || typeof principal !== 'object') return fn()
+    return principalContext.run({ principal }, fn)
+}
+
+export function currentPrincipal() {
+    return principalContext.getStore()?.principal ?? null
+}

package/src/render.js

@@ -149,6 +149,13 @@ export default async ({ entity, options, config, context, state, logger, port, t
         } catch { /* package not installed at this level — fine, try next */ }
 
         const resolveLocations = [
+            // What the descriptor itself said, first: it is the only entry
+            // that does not guess from the name. Everything below assumes a
+            // package called `mikser-io-<pluginName>`, which is true of every
+            // plugin named for its renderer and false of every one that ships
+            // alongside other things — mikser-io-assets ships two. See
+            // workerSafeOptions.
+            options.pluginModules?.[pluginName],
             path.join(options.workingFolder, 'node_modules', `mikser-io-${pluginName}/index.js`),
             nodeModulesResolved,
             path.join(options.workingFolder, 'plugins', `${pluginName}.js`),
@@ -322,7 +329,22 @@ export default async ({ entity, options, config, context, state, logger, port, t
     }
 
     const rendererPlugin = plugins[`render-${renderer}`]
-    const output = await rendererPlugin?.render({ entity, options, config: rendererPlugin?.options, context, plugins, runtime, state, logger, track })
+    // A missing HELPER announces itself — the template asks for something that
+    // is not there and the engine reports a render error. A missing RENDERER
+    // did not: the optional call returned undefined, the entity produced no
+    // output, and the only trace was one log line above. That is how
+    // `render-preset` went unresolvable on workers for two releases while
+    // every build stayed green.
+    //
+    // An entity was asked for and nothing rendered it. That is a fault, and it
+    // reads as one now.
+    if (typeof rendererPlugin?.render !== 'function') {
+        throw new Error(`Renderer "${renderer}" is not loaded, so ${entity?.id ?? 'this entity'} `
+            + `cannot be rendered. Its plugin resolved to nothing: either it is missing from the `
+            + `config, or it is a plugin a worker cannot find by name — see the "Render plugin `
+            + `render-${renderer} not found" line above.`)
+    }
+    const output = await rendererPlugin.render({ entity, options, config: rendererPlugin.options, context, plugins, runtime, state, logger, track })
 
     // One shape for both dispatch modes, so the engine unpacks in one place
     // rather than branching on how the render happened. An inline render folds

package/src/utils/entity.js

@@ -8,6 +8,7 @@ import { contentType } from 'mime-types'
 import { minimatch } from 'minimatch'
 import { mkdir, open, readFile, unlink, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
+import { missingCollectionWrite } from '../auth.js'
 
 // Extension → mime type lookup for rendered outputs. Used anywhere an
 // entity's destination is being served over HTTP (the api plugin's
@@ -371,6 +372,24 @@ export function projectMeta(meta) {
  *   remove(relativePath: string): Promise<void>,
  * }}
  */
+// Refuse a write the acting principal may not make.
+//
+// Here rather than at each caller, and for the reason the change-set hook one
+// line below is here: this is the lowest write primitive, so a plugin that
+// has never heard of capabilities is still bounded by them. The alternative
+// is every writer remembering, and the one that forgets is the one that
+// leaks.
+//
+// Throws rather than returning a refusal because `write` has no refusal
+// channel — it returns a uri — and a caller that ignores a falsy return would
+// report success for a write that never happened.
+function refuseUnlessMayWrite(collection) {
+    const missing = missingCollectionWrite(collection)
+    if (!missing) return
+    throw new Error(`Refused: writing to ${collection} needs ${missing}, `
+        + 'which this credential does not carry.')
+}
+
 export function useCollection(runtime, name) {
     function resolveFolder() {
         const folder = runtime?.options?.[`${name}Folder`]
@@ -402,6 +421,7 @@ export function useCollection(runtime, name) {
         resolveWithin,
 
         async write(relativePath, content = '') {
+            refuseUnlessMayWrite(name)
             const uri = resolveWithin(relativePath)
             await mkdir(path.dirname(uri), { recursive: true })
             await writeFile(uri, content, 'utf8')
@@ -415,6 +435,7 @@ export function useCollection(runtime, name) {
         },
 
         async remove(relativePath) {
+            refuseUnlessMayWrite(name)
             const uri = resolveWithin(relativePath)
             await unlink(uri)
             runtime.recordChangeSetWrite?.({ uri, operation: 'delete' })

package/src/utils/index.js

@@ -15,5 +15,5 @@ export { checksum, checksumOf, diffInputParts, inputHashOf, inputPartsOf, normal
 export { JUNK_IGNORE, isJunkPath, junkFilter, junkIgnore, registerJunk } from './junk.js'
 export { matchesLibrary } from './library.js'
 export { isLoopback, loopbackOnly } from './net.js'
-export { siteRelativeUrl, siteRootFor, writeEntity, writeOutput } from './output.js'
+export { siteRelativeUrl, siteRootFor, writeEntity, writeOutput, registerSourceFormat, sourceFormatFor, validateSource } from './output.js'
 export { extractRefs, isRefKey, lookupKeys, matchesRef, refFilter } from './refs.js'

package/src/utils/output.js

@@ -37,44 +37,159 @@ import { lstat, mkdir, open, readFile, stat, unlink, writeFile } from 'node:fs/p
 // Returns the absolute path that was written. The watcher will see the
 // change just like any external edit — the entity re-enters the lifecycle
 // naturally on the next cycle.
+// How a source file carries its meta, and how to put it back.
+//
+// Front matter is one answer, not the answer. A `.yml` or `.json` entity IS
+// its meta — there is no body — and treating every file as front-matter did
+// not merely format it oddly, it destroyed it: with no `---` to find, the
+// whole document was taken as the BODY and the patch written above it as
+// fresh front matter. A one-key rename turned a price list into a two-key
+// document with the real one quoted underneath as inert text, and nothing
+// threw. refs.rename reaches this for every referring entity, which is the
+// largest fan-out any single request has.
+//
+// Registered and dispatched the way provenance registers its readers: last
+// registered is checked first, and the catch-all goes in first so it is
+// consulted last. A format plugin adds its own without touching this file.
+//
+//   test(entity, raw)      does this handler own this source?
+//   write({ raw, patch })  the complete new file contents
+//   validate(text)         null if it parses, else why not — so an edit can
+//                          be refused before it lands rather than found at
+//                          the next build
+//
+// `patch` rather than a merged meta, deliberately: a handler that can edit its
+// source in place should be allowed to. The yaml one does, so comments and
+// untouched values survive an edit that names one key.
+const sourceFormats = []
+
+export function registerSourceFormat(name, { test, write, validate = null }) {
+    if (!name || typeof test !== 'function' || typeof write !== 'function') {
+        throw new Error('registerSourceFormat(name, { test, write }) requires all three')
+    }
+    sourceFormats.unshift({ name, test, write, validate })
+    return () => {
+        const at = sourceFormats.findIndex(h => h.name === name)
+        if (at >= 0) sourceFormats.splice(at, 1)
+    }
+}
+
+// Does this text still parse as what the file is? `null` when it does, and
+// when the format has no parser to ask — the answer to "is this valid" for a
+// stylesheet is not this module's to give.
+export function validateSource(entity, text) {
+    const handler = sourceFormatFor(entity, text)
+    if (typeof handler?.validate !== 'function') return null
+    try { return handler.validate(text) } catch (err) { return err.message }
+}
+
+export function sourceFormatFor(entity, raw = '') {
+    for (const handler of sourceFormats) {
+        try {
+            if (handler.test(entity, raw)) return handler
+        } catch { /* a handler that throws is a handler that declines */ }
+    }
+    return sourceFormats[sourceFormats.length - 1]
+}
+
+// The format an entity is in, by what the catalog recorded and, failing that,
+// by its extension — a caller holding only a uri is one this must still answer
+// for.
+function formatOf(entity) {
+    if (entity?.format) return String(entity.format).toLowerCase()
+    return path.extname(entity?.uri ?? '').replace(/^\./, '').toLowerCase()
+}
+
+function applyPatch(target, patch) {
+    const next = { ...target }
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) delete next[key]
+        else next[key] = value
+    }
+    return next
+}
+
+// A text document with a `---` block, or one that should grow one. Registered
+// first, so it is checked last: this is the catch-all.
+registerSourceFormat('front-matter', {
+    test: () => true,
+    // Only the block is parseable; the body is whatever the renderer makes of
+    // it. A file with no front matter has nothing here to be wrong.
+    validate(text) {
+        if (!fm.test(text)) return null
+        try { fm(text); return null } catch (err) { return err.message }
+    },
+    write({ raw, patch }) {
+        const parsed = fm.test(raw) ? fm(raw) : null
+        const body = parsed ? (parsed.body ?? '') : raw
+        const meta = applyPatch(parsed?.attributes ?? {}, patch)
+        // No meta left — write just the body, rather than a `---`/`---` shell
+        // that some tooling reads as broken front matter.
+        if (Object.keys(meta).length === 0) return body
+        return `---\n${yaml.stringify(meta)}---\n${body}`
+    },
+})
+
+// A YAML document is meta all the way down.
+//
+// Patched through the document AST rather than re-serialized, so comments and
+// every value the patch does not name survive. Not byte-perfect: the emitter
+// re-flows block scalars to its own width, so hand-wrapped prose moves. That
+// is a formatting change, where re-serializing would have been a content one.
+registerSourceFormat('yaml', {
+    validate(text) {
+        const errors = yaml.parseAllDocuments(text).flatMap(document => document.errors)
+        return errors.length ? errors[0].message : null
+    },
+    // On the format alone. `fm.test` is not a safe second opinion here: a
+    // multi-document YAML file has a `---` between its documents and reads as
+    // front matter to it, so consulting it sent exactly the files with the
+    // most to lose down the wrong path.
+    test: (entity) => ['yml', 'yaml'].includes(formatOf(entity)),
+    write({ raw, patch }) {
+        // Every document, not the first. parseDocument on a multi-document
+        // source returns one carrying errors, and stringifying it throws —
+        // loud, but it refuses a file it could have patched. The meta belongs
+        // to the first document; the rest are copied through untouched.
+        const documents = raw.trim() ? yaml.parseAllDocuments(raw) : [yaml.parseDocument('')]
+        const target = documents[0]
+        for (const [key, value] of Object.entries(patch)) {
+            if (value === null) target.deleteIn([key])
+            else target.setIn([key], value)
+        }
+        return documents.map(document => document.toString()).join('')
+    },
+})
+
+// JSON has no comments to keep and no body to preserve, so this is a plain
+// round-trip — but the indent is read off the file rather than imposed, so a
+// one-key patch does not reformat every line of a 4-space document.
+registerSourceFormat('json', {
+    validate(text) {
+        if (!text.trim()) return null
+        try { JSON.parse(text); return null } catch (err) { return err.message }
+    },
+    test: (entity) => formatOf(entity) === 'json',
+    write({ raw, patch }) {
+        const current = raw.trim() ? JSON.parse(raw) : {}
+        const indent = raw.match(/^[ \t]+/m)?.[0] ?? '  '
+        return JSON.stringify(applyPatch(current, patch), null, indent) + '\n'
+    },
+})
+
 export async function writeEntity(entity, patch = {}) {
     if (!entity?.uri) {
         throw new Error('writeEntity: entity.uri is required')
     }
 
-    let currentMeta = {}
-    let body = ''
+    let raw = ''
     try {
-        const content = await readFile(entity.uri, 'utf8')
-        if (fm.test(content)) {
-            const parsed = fm(content)
-            currentMeta = parsed.attributes ?? {}
-            body = parsed.body ?? ''
-        } else {
-            body = content
-        }
+        raw = await readFile(entity.uri, 'utf8')
     } catch (err) {
         if (err.code !== 'ENOENT') throw err
-        // Fresh file — start from an empty meta + body.
-    }
-
-    const newMeta = { ...currentMeta }
-    for (const [k, v] of Object.entries(patch)) {
-        if (v === null) delete newMeta[k]
-        else newMeta[k] = v
+        // Fresh file — the handler starts from empty source.
     }
-
-    let newContent
-    if (Object.keys(newMeta).length > 0) {
-        // yaml.stringify always emits a trailing newline.
-        const yamlStr = yaml.stringify(newMeta)
-        newContent = `---\n${yamlStr}---\n${body}`
-    } else {
-        // No meta left — write just the body. Avoids `---\n---\n<body>`
-        // shells that some tooling treats as "broken frontmatter."
-        newContent = body
-    }
-
+    const newContent = sourceFormatFor(entity, raw).write({ raw, patch, entity })
     await mkdir(path.dirname(entity.uri), { recursive: true })
     await writeFile(entity.uri, newContent, 'utf8')
     // The other file-writing primitive. A rename cascade rewrites every

package/src/write.js

@@ -18,11 +18,11 @@
 // gap this closes: the safety belongs to the write, not to one transport.
 
 import path from 'node:path'
-import { readdir } from 'node:fs/promises'
+import { readdir, readFile } from 'node:fs/promises'
 
 import runtime from './runtime.js'
 import { readEntity, findEntities } from './catalog.js'
-import { useCollection, checksum, readEntityContent, lookupKeys } from './utils/index.js'
+import { useCollection, checksum, readEntityContent, lookupKeys, validateSource } from './utils/index.js'
 import { nextCycleId, whenCycleCompletes } from './report.js'
 import { recordChangeSetWrite, currentChangeSet } from './changeset.js'
 
@@ -431,3 +431,145 @@ function referrersOf(entity) {
     }
     return [...found.values()]
 }
+
+// Change a source file by naming the text to change, not by resending it.
+//
+// The alternative — and until now the only one — is a whole-file rewrite. For
+// a model that is a silent-corruption machine: to change one price in a
+// 900-line price list it must re-emit all 900 lines, and a line it quietly
+// drops is indistinguishable downstream from a line someone meant to delete.
+// `ifChecksum` catches a stale READ; nothing catches a lossy WRITE.
+//
+// An anchor cannot lose what it does not name. The only bytes that change are
+// the ones matched, so everything else is not merely preserved — it is never
+// rewritten. That also makes the concurrency check sharper than a checksum: a
+// checksum refuses when ANY part of the file moved, an anchor refuses when the
+// part you are editing moved, and those are different questions.
+//
+// Three refusals, and all of them are the good kind — stop and look, never
+// "wrote the wrong thing":
+//
+//   anchor-not-found    the text is not there; the file is not what you read
+//   anchor-ambiguous    it is there more than once; say more, or pass `all`
+//   would-not-parse     the result is not valid in this file's format
+//
+// The last is the one a whole-file write can never offer. Today a model can
+// emit invalid YAML and the build finds out; here the file never lands.
+export async function editEntitySource({
+    id,
+    collection,
+    relativePath,
+    find,
+    replace = '',
+    all = false,
+    ifChecksum,
+    dryRun = false,
+    awaitCycle = false,
+    changeSet,
+    summary,
+    principal,
+} = {}) {
+    if (typeof find !== 'string' || find === '') {
+        return { ok: false, refused: 'no-anchor', error: '`find` must be a non-empty string.' }
+    }
+    if (id) {
+        const located = await locateEntityFile(id)
+        if (located.error) return { ok: false, refused: 'unresolvable-id', error: located.error }
+        if (collection && collection !== located.collection) {
+            return {
+                ok: false,
+                refused: 'collection-mismatch',
+                error: `id ${id} is in collection ${located.collection}, not ${collection}. Pass one or the other.`,
+            }
+        }
+        collection ??= located.collection
+        relativePath ??= located.relativePath
+    }
+    if (!collection || !relativePath) {
+        return {
+            ok: false,
+            refused: 'incomplete-target',
+            error: 'Pass either `id` (for an existing entity) or both `collection` and `relativePath`.',
+        }
+    }
+
+    let handle
+    let uri
+    try {
+        handle = useCollection(runtime, collection)
+        uri = handle.resolveWithin(relativePath)
+    } catch (err) {
+        return { ok: false, refused: 'invalid-target', collection, relativePath, error: err.message }
+    }
+
+    const before = await fileChecksum(uri)
+    if (before === null) {
+        return {
+            ok: false,
+            refused: 'no-such-file',
+            collection, relativePath,
+            error: 'There is nothing here to edit. Use the whole-file write to create a file.',
+        }
+    }
+    if (ifChecksum !== undefined && ifChecksum !== before) {
+        return {
+            ok: false,
+            refused: 'checksum-mismatch',
+            collection, relativePath,
+            expectedChecksum: ifChecksum, currentChecksum: before,
+            hint: 'The file changed since you read it. Re-read it and check your anchor still says what you meant.',
+        }
+    }
+
+    const current = await readFile(uri, 'utf8')
+    const occurrences = current.split(find).length - 1
+    if (occurrences === 0) {
+        return {
+            ok: false,
+            refused: 'anchor-not-found',
+            collection, relativePath, currentChecksum: before,
+            error: 'That text is not in the file.',
+            hint: 'Re-read the entity: either it changed, or the anchor carries whitespace or a line break it does not have.',
+        }
+    }
+    if (occurrences > 1 && !all) {
+        return {
+            ok: false,
+            refused: 'anchor-ambiguous',
+            collection, relativePath, occurrences, currentChecksum: before,
+            error: `That text appears ${occurrences} times.`,
+            hint: 'Extend `find` with surrounding lines until it is unique, or pass `all: true` to change every one.',
+        }
+    }
+
+    // One expression for both, because the refusals above have already made
+    // the counts exact: `all` means "however many there are", and without it
+    // there is exactly one. (split/join replaces each match in the ORIGINAL,
+    // so a replacement containing the anchor does not compound.)
+    const content = current.split(find).join(replace)
+
+    // Refused before it lands, which is the guarantee a whole-file write has
+    // no way to make. Formats with no parser say nothing and pass.
+    const invalid = validateSource({ uri, collection }, content)
+    if (invalid) {
+        return {
+            ok: false,
+            refused: 'would-not-parse',
+            collection, relativePath, currentChecksum: before,
+            error: `The result is not valid ${path.extname(uri).replace('.', '') || 'content'}: ${invalid}`,
+            hint: 'Nothing was written. Check the replacement for indentation or quoting the format needs.',
+        }
+    }
+
+    // Through the whole-file write, so containment, the change set, the cycle
+    // id, sibling destinations and the collection capability gate are the same
+    // ones every other write goes through rather than a second set that can
+    // drift. `before` as the checksum closes the window between the read above
+    // and the write below.
+    const written = await writeEntitySource({
+        collection, relativePath, content,
+        ifChecksum: before,
+        dryRun, awaitCycle, changeSet, summary, principal,
+    })
+    return written.ok ? { ...written, replacements: all ? occurrences : 1 } : written
+}