mikser-io 9.42.0 → 9.43.1

package/docs/api-reference.md

@@ -483,6 +483,79 @@ Query types throughout: function, lodash match object, or `undefined` for all.
 
 ---
 
+## Writing source files
+
+`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.
+
+### `writeEntitySource(options)`
+
+```js
+import { writeEntitySource } from 'mikser-io'
+
+const preview = await writeEntitySource({
+    id: '/documents/about.md',
+    content: next,
+    dryRun: true,          // writes nothing; reports what it would re-render
+})
+
+const result = await writeEntitySource({
+    id: '/documents/about.md',
+    content: next,
+    ifChecksum: preview.currentChecksum,
+})
+```
+
+| Option | Meaning |
+| --- | --- |
+| `id` | Catalog id of an existing entity. Alternative to the pair below. |
+| `collection` + `relativePath` | Where to write. Required unless `id` is given. |
+| `content` | The COMPLETE file. Anything omitted is deleted — there is no patch mode. |
+| `ifChecksum` | Only write if the file's current DISK checksum equals this. |
+| `dryRun` | Write nothing; return the blast radius and any advisory. |
+| `awaitCycle` | Resolve once the cycle that picks the write up finishes, with its build report attached as `report`. |
+
+**Never throws for an expected outcome.** A bad id, a path that escapes the
+collection, a checksum that no longer matches — each returns
+`{ ok: false, refused }` with the facts needed to retry, because those are
+answers rather than faults. `refused` is one of `unresolvable-id`,
+`collection-mismatch`, `incomplete-target`, `invalid-target`,
+`checksum-mismatch`.
+
+**Containment.** `relativePath` cannot leave the collection folder. This
+matters because the path often comes from a request body or a CMS form, and
+`path.join(folder, '../../x')` resolves outside the folder and writes there. It
+is resolved and then contained rather than rejected on a literal `..`, so
+`blog/../about.md` still works. The refusal happens before anything stats the
+file — reporting a checksum for an out-of-tree path is a disclosure on its own.
+
+**The precondition is not a lock.** A writer landing between the check and the
+write still wins. It closes the window that matters in practice: read, think,
+write back a whole file built from a copy that is now stale.
+
+`ifChecksum` is compared against the DISK. `readEntity`'s `checksum` is the
+catalog's, which lags between builds — pass `diskChecksum`, or the
+`currentChecksum` a refusal hands back.
+
+### Advisories
+
+`contentAdvisories(entity, content)` names files a caller must not edit blind,
+from `meta.specLocked` / `meta.generated` or from a header in the first 40
+lines. Two kinds, kept apart because the instruction differs: `spec-locked`
+means the bytes answer to a document outside the repo, `generated` means
+editing the file is pointless because the next build overwrites it.
+`advisoryWarning(advisories)` renders one line of prose for a response meant to
+be read rather than parsed. Both are reported by `writeEntitySource` — on the
+dry run and again on the way out, since a caller that never read the file is
+exactly the one that needs telling.
+
+`siblingDestinations(folder, relativePath)` reports files differing only by
+extension, which may render to the same destination.
+`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.
+
 ## Search
 
 `queryEntities` sifts **meta**. `searchEntities` answers the other question —
@@ -545,6 +618,299 @@ it, in any text format, with no per-language grammar involved. It returns the
 line rather than a verdict about it, so where the heuristic is wrong the
 evidence is in the result.
 
+## Content
+
+Reading an entity's source, and deciding what "source" even means for it.
+
+### `readEntityContent(entity, { reload } = {})`
+
+Returns one of `{ content }`, `{ contentError }`, `{ contentSkipped }` — an
+object to `Object.assign` onto the entity, or use directly. Dispatches by URI
+scheme: plain paths and `file://` read from disk, `http(s)://` goes through the
+built-in provider, anything else dynamic-imports `mikser-io-provider-<scheme>`.
+
+`entity.content` already being a string short-circuits the whole dispatch, which
+spares re-fetching a remote document a source plugin eagerly pulled in. Pass
+`reload: true` when you want the bytes **as they are now** — between builds the
+catalog copy and the file on disk part ways, and a whole-file rewrite built from
+the catalog copy silently discards whatever changed underneath. An entity with
+no `uri` keeps what it has rather than erroring.
+
+### `looksTextual(buffer)` / `isTextEntity(entity)`
+
+`looksTextual` answers "is this text?" from the BYTES: no NUL and a clean UTF-8
+decode. This is what decides whether content comes back, and it is why a
+`.liquid`, `.njk`, `.toml` or a format nobody has written yet is readable
+without being added to a list first.
+
+`isTextEntity` is a cheap extension guess with no I/O. It is a **hint** — the
+extension list behind it is hand-maintained and therefore wrong about anything
+not yet added. Never gate a read on it.
+
+### `mimeForEntity(entity)`
+
+Content type for the entity's `destination`, from the IANA registry via
+`mime-types`. Null when the entity has no destination or the extension is
+unregistered.
+
+### `checksumOf(content)` / `checksum(uri)`
+
+`checksumOf` hashes a string; `checksum` hashes a file, sampling head and tail
+for large ones rather than reading the whole thing.
+
+## Collections and sources
+
+### `useCollection(runtime, name)`
+
+The folder behind a collection, and guarded writes into it.
+
+```js
+const documents = useCollection(runtime, 'documents')
+documents.folder                          // absolute path
+await documents.write('blog/post.md', text)
+await documents.remove('blog/post.md')
+documents.resolveWithin('blog/post.md')   // absolute path, or throws
+```
+
+`write`, `remove` and `resolveWithin` refuse a path that resolves outside the
+collection folder. This matters whenever the path comes from a request body or
+a form: joining a folder with `../../x` lands outside it. The path is resolved
+and then contained rather than rejected on a literal `..`, so `blog/../post.md`
+still works.
+
+### `useSource(core, options)`
+
+Codifies the folder-of-files pattern: scan a folder, emit entities, watch for
+changes, sweep deletions.
+
+| Option | Meaning |
+| --- | --- |
+| `collection`, `type`, `folder` | Required. |
+| `extensions` | Default `['*']`. |
+| `ignore` | Glob patterns to skip. |
+| `phase` | `'loaded'` (default) or another lifecycle phase. |
+| `content` | Load file content into the entity at sync time. |
+| `load` | `async (entity) => meta` — your parse step. |
+| `idPrefix` | Defaults to `/<collection>`. |
+| `stripExtensionFromId` | Default false (documents style). |
+| `progress` | Progress label. |
+
+### `sweepDeleted(collection, scanned, onDelete, ownerPrefix)`
+
+Removes catalog entities whose files are gone. **`ownerPrefix` is mandatory and
+load-bearing.** Collections are multi-emitter: the file source scans a folder,
+but a CSV plugin fans rows into the same collection, and a remote sync emits
+there with a `gdrive://` uri. The sweep only considers entities whose `uri` is
+rooted under the prefix — without it, every cycle's file sweep wipes every
+other emitter's entities.
+
+### `useRenderer(runtime, { defaultTimeout } = {})`
+
+Returns `{ render }` — the batching renderer the engine dispatches through,
+with a per-task timeout (default 30s). A plugin that needs to render something
+outside the normal cycle goes through this rather than importing a renderer
+package directly.
+
+## Query context
+
+`queryContext` is the `AsyncLocalStorage` that lets a catalog query made during
+a render record itself as a dependency, so an aggregate page invalidates when a
+new matching entity lands.
+
+It only works if the whole tree shares ONE module instance of `mikser-io`. In
+the side-by-side dev layout that means the npm workspace at the parent folder
+is not ergonomics but correctness: without it, npm installs a second copy into
+a sibling's own `node_modules`, a plugin's `queryContext` is then a different
+AsyncLocalStorage than the engine's, queries record no edges, and index pages,
+sitemaps and feeds silently stop rebuilding. Production consumers resolve both
+from their own tree, so the problem is local to the dev workspace.
+
+## Auth
+
+Building a token-gated or loopback-only route.
+
+| Export | Does |
+| --- | --- |
+| `resolveAuth(config)` | build a verifier from endpoint config |
+| `requireAuth(verifier, options)` | Express middleware |
+| `authorize(req, verifier, { allowRemote, trustLoopback })` | the check itself |
+| `bearer({ token, name, subject, capabilities, scope })` | a static-token verifier |
+| `loopbackOnly({ message })` | middleware refusing non-loopback callers |
+| `hasCapability(principal, capability)` | test a resolved principal |
+
+A principal may carry a `scope` — a sift filter that narrows what it can see.
+Anything reading content on a principal's behalf must apply it; see the warning
+under [Search](#search) for why an unscoped read behind a scoped endpoint is
+the failure mode to watch for.
+
+## References
+
+The `$`-keyed reference graph (ADR-0007), reachable at `runtime.refs` or via
+`useRefsIndex()`.
+
+| Method | Answers |
+| --- | --- |
+| `inboundFor(target)` / `outboundFor(source)` | static `$`-ref edges |
+| `dynamicInboundFor` / `dynamicOutboundFor` | render-time edges (layout, partial, query, lookup) |
+| `inverseClosureOf(seeds)` | everything reachable backwards — what invalidation walks |
+| `resolveRefIds(ref)` | which entities a ref string resolves to |
+| `rename({ from, to })` | rewrite refs across the catalog, as one cascade |
+| `allRefs()` / `size()` | inventory |
+
+### `refFilter(ref)` / `matchesRef(entity, ref)` / `lookupKeys(entity)`
+
+One relation in three directions — as a catalog query, as a predicate, and in
+reverse. **They must be changed together.** A key present in one and missing
+from the others is silent: `meta.url` once lived only in `refFilter`, which
+made every `$`-ref to a served path non-invalidating without any error
+anywhere.
+
+### `extractRefs(meta)` / `isRefKey(key)` / `expandEntity(entity, paths, options)` / `projectMeta(meta)`
+
+Find the `$`-keys in a meta tree, test one key, inline referenced entities
+along dotted paths, and drop `$`-keys for output.
+
+## Provenance
+
+Where a value was **written** — source file, field path, line, column.
+
+```js
+const positions = await useProvenance().positionsFor(entity)
+// { 'items[2].label': { line, col }, … }
+```
+
+| Method | Answers |
+| --- | --- |
+| `positionsFor(entity)` | every leaf of the entity's meta |
+| `locate(entity, fieldPath)` | one position, or null |
+| `forget(id)` | drop a cached entry |
+| `size()` | how many entries are cached |
+
+Field paths are free — they come from walking meta, already in memory. Line and
+column need one parse of the raw source, done **on demand** and cached against
+the entity's checksum, so a build pays nothing.
+
+`registerProvenanceFormat(name, { test, positions })` adds a format rather than
+special-casing one. A format whose parser reports no ranges registers a
+`probeFormat(name, { test, parse })` instead, which recovers positions in one
+pass without the parser's help.
+
+## Manifest and outputs
+
+`runtime.manifest` holds render snapshots. Full treatment lives in
+[diagnostics.md](diagnostics.md) — indexed by the question each surface
+answers — but the ones an application reaches for:
+
+| Method | Answers |
+| --- | --- |
+| `affectedBy(entity)` | which destinations would re-render if this changed |
+| `collisions()` | destinations more than one entity writes to |
+| `snapshotsFor(id)` / `snapshotsAt(destination)` | what rendered, and from what |
+| `skipDecision(entity, …)` | the engine's own skip rule, with the reason |
+
+`sourcesOf(destination)` is the reverse lookup: what produced this built file,
+each tagged with how it got there. `sourcesBehind(snapshot)` does the same from
+a snapshot you already hold. `resolveOutputPath(destination)` maps a
+destination to a path on disk, and `writeOutput(file, bytes)` writes one.
+
+## Tools
+
+The tool registry — named, described, invokable capabilities. Two agent
+workflows exist and are equally real: one speaking MCP over HTTP, one running
+the CLI and reading its output. A tool registered here reaches both.
+
+```js
+registerTool('audit', {
+    description: 'What this answers, in prose an agent will actually read.',
+    inputSchema: { path: { type: 'string', required: true } },
+}, async ({ path }) => ok({ … }))
+```
+
+`invokeTool(name, args)` runs one — it accepts the bare name or the `mikser_`
+prefixed form. `toolNames()`, `toolSchema(name)` and `toolSchemas()` enumerate.
+`toolResultText(result)` pulls the text back out of a tool result, and
+`toolResultFailed(result)` says whether it failed.
+
+The registry is deliberately zod-free: schemas use a neutral
+`{ type, required?, description? }` vocabulary, because it must not depend on
+one transport's schema library. `mikser-io-mcp` converts to zod at bind time.
+
+## Routes
+
+An Express router stack has the paths but not the intent. Plugins declare each
+mount as they make it, so a facade generator, a healthcheck list or a
+diagnostics view can read one inventory.
+
+```js
+registerRoute({
+    path: '/api',
+    plugin: 'api',
+    reachability: 'public',   // 'public' | 'token' | 'loopback'
+    streaming: false,         // true for SSE/WS, which a facade must not buffer
+})
+```
+
+`registerRoute` also folds in the origin/URL building and the standard boot
+log. `listRoutes()` returns the inventory; `reachabilityOf` and `routeLocation`
+answer about one route. `isLoopback(ip)` is the check behind
+`reachability: 'loopback'` — note that the server's trust-proxy default is
+`'loopback'`, not Express's `false`, which is what keeps that gate correct
+behind a same-host reverse proxy.
+
+## Cycles and the build report
+
+`nextCycleId()` reserves the id of the cycle a pending change will be picked up
+by; `whenCycleCompletes(id)` resolves once it finishes, with its report.
+Together they turn "write and guess" into one call that says what the edit
+invalidated. `currentCycle()` and `buildReport()` read the cycle in progress and
+the last completed report.
+
+## Logging
+
+`addLogTransport({ target, options, level })` adds a pino transport from a
+plugin factory or any later hook. Called before the logger is built, it queues;
+after, it live-rebuilds the multistream. This is what lets Better Stack,
+Datadog, Loki, Axiom or Sentry ship as ordinary sibling plugins with no engine
+change per vendor.
+
+Prefer this over `runtime.config.logging.transports` from plugin code — the
+declarative form is for user config.
+
+## Junk
+
+`registerJunk({ ignore, match })` teaches the engine to skip editor and OS
+debris; `isJunkPath(filePath)` asks.
+
+## What is not here
+
+Plugin factories — `yaml()`, `json()`, `frontMatter()`, `assets()`,
+`resources()`, `shares()`, `observer()`, `mapper()`, `commands()`,
+`renderHbs()` — are configured rather than called, and live in
+[configuration.md](configuration.md).
+
+`mikser-io` exports more than this page covers, deliberately. Five kinds of
+export are engine plumbing:
+
+- **Factories the engine calls once** — `createManifest`, `createRefs`,
+  `createProvenance`, `createSqliteDatabase`, `createTrack`, `createIndex`,
+  `createSubscribers`.
+- **Schema constants** the test suites build against rather than copying —
+  `SNAPSHOTS_SCHEMA`, `REFS_SCHEMA`, `FAILURES_SCHEMA`, `PROVENANCE_SCHEMA`.
+- **Report and cycle internals** — `reportRendered`, `reportSkipped`,
+  `reportError`, `emitReport`, `resetReport`, `finishCycle`, `inputHashOf`.
+- **Render-time tracking** — `recordReads`, `untrack`, `trackedInfo`,
+  `serializeTrack`, `mergeTrack`, `observeConsumed`. These implement
+  dependency recording; a plugin observes its RESULTS through
+  `runtime.manifest` and `runtime.refs` instead.
+- **Template helper plumbing** — `assetUrlHelper`, `resourceUrlHelper`,
+  `hrefUrlHelpers`, `fileHelpers`, `renderPreset`, wired into renderers rather
+  than called.
+
+They are exported because the engine's own modules and its test suite need them
+across file boundaries, not as an invitation. If you find yourself reaching for
+one from a plugin, that is worth raising — it usually means a capability is
+missing from the surface above.
+
 ## Database
 
 ```js

package/index.js

@@ -12,6 +12,7 @@ export * from './src/database/index.js'
 export * from './src/journal.js'
 export * from './src/catalog.js'
 export * from './src/search.js'
+export * from './src/write.js'
 export * from './src/refs.js'
 export * from './src/manifest.js'
 export * from './src/provenance.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.42.0",
+  "version": "9.43.1",
   "description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
   "main": "index.js",
   "exports": {

package/src/utils.js

@@ -1077,20 +1077,38 @@ export function useCollection(runtime, name) {
         return folder
     }
 
+    // A path that cannot leave the collection folder.
+    //
+    // `path.join(folder, '../../x')` resolves outside the folder and writes
+    // there, which turns a collection handle into an arbitrary-write
+    // primitive the moment a relative path comes from a request body or a CMS
+    // form. Resolved and then contained rather than rejected on a literal
+    // `..`, so `a/../b.md` — which lands inside — still works.
+    function resolveWithin(relativePath) {
+        const folder = resolveFolder()
+        const uri = path.resolve(folder, relativePath ?? '')
+        const root = path.resolve(folder)
+        if (uri !== root && !uri.startsWith(root + path.sep)) {
+            throw new Error(
+                `Path escapes the ${name} collection: ${JSON.stringify(relativePath)} resolves outside ${root}`)
+        }
+        return uri
+    }
+
     return {
         name,
         get folder() { return resolveFolder() },
+        resolveWithin,
 
         async write(relativePath, content = '') {
-            const uri = path.join(resolveFolder(), relativePath)
+            const uri = resolveWithin(relativePath)
             await mkdir(path.dirname(uri), { recursive: true })
             await writeFile(uri, content, 'utf8')
             return uri
         },
 
         async remove(relativePath) {
-            const uri = path.join(resolveFolder(), relativePath)
-            await unlink(uri)
+            await unlink(resolveWithin(relativePath))
         },
     }
 }

package/src/write.js

@@ -0,0 +1,279 @@
+// Write a source file back, with the checks that make a whole-file rewrite
+// safe to perform without having watched the file the whole time.
+//
+// The only write mode is whole-file: there is no patch. That makes the write
+// itself the easy part and everything around it the point —
+//
+//   - a checksum precondition, so a rewrite built from a stale copy is
+//     refused instead of silently discarding whoever edited in between
+//   - a dry run reporting which destinations the write would re-render
+//   - advisories naming a file that is GENERATED or answers to an external
+//     spec, which a caller must not edit blind
+//   - siblings that could render to the same destination
+//   - containment, so a relative path from a form or a request body cannot
+//     write outside the collection folder
+//
+// An editing agent gets these through mikser-io-mcp. An application driving
+// mikser as a CMS writes its own files and gets none of them, which is the
+// 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 runtime from './runtime.js'
+import { readEntity, findEntities } from './catalog.js'
+import { useCollection, checksum, readEntityContent } from './utils.js'
+import { nextCycleId, whenCycleCompletes } from './report.js'
+
+// How far into a file to look for a marker. A header nobody reads is not a
+// header; one buried 200 lines down is not either.
+const HEADER_SCAN_LINES = 40
+
+// Files a caller must not edit blind, read from the bytes themselves.
+//
+// Two kinds, kept apart because the instruction differs. `spec-locked` means
+// the bytes answer to a document outside the repo — change it and the site
+// stops matching something a human signed off. `generated` means editing the
+// file is pointless, because the next build overwrites it.
+const HEADER_PATTERNS = [
+    { kind: 'spec-locked', re: /^\W*spec source:\s*(.+?)\s*$/i },
+    { kind: 'generated',   re: /^\W*(?:generated by|do not edit)\b:?\s*(.*?)\s*$/i },
+]
+
+export function contentAdvisories(entity, content) {
+    const found = []
+    const push = (kind, detail, via, line) => {
+        if (found.some(a => a.kind === kind)) return
+        found.push({ kind, detail: detail || null, via, ...(line ? { line } : {}) })
+    }
+    // Explicit meta wins: someone wrote it down as data, on purpose.
+    if (entity?.meta?.specLocked) {
+        push('spec-locked', typeof entity.meta.specLocked === 'string' ? entity.meta.specLocked : null, 'meta.specLocked')
+    }
+    if (entity?.meta?.generated) {
+        push('generated', typeof entity.meta.generated === 'string' ? entity.meta.generated : null, 'meta.generated')
+    }
+    if (typeof content === 'string') {
+        const lines = content.split('\n', HEADER_SCAN_LINES)
+        for (let i = 0; i < lines.length; i++) {
+            for (const { kind, re } of HEADER_PATTERNS) {
+                const m = re.exec(lines[i])
+                if (m) push(kind, m[1], 'header', i + 1)
+            }
+        }
+    }
+    return found
+}
+
+// One line of prose for a response that has to be read, not parsed.
+export function advisoryWarning(advisories) {
+    if (!advisories?.length) return null
+    return advisories.map(a => a.kind === 'spec-locked'
+        ? `SPEC-LOCKED: ${a.detail ?? 'this file answers to an external specification'}`
+            + ' — changing it may break a signed-off design. Confirm against the spec before writing.'
+        : `GENERATED: ${a.detail ?? 'this file is produced by the build'}`
+            + ' — edit its source instead; the next build overwrites this.').join(' ')
+}
+
+// Files beside this one that differ only by extension.
+//
+// An empty `index.md` sitting next to a real `index.yml` renders to the same
+// destination; whichever renders last wins and the other output is discarded.
+// The destination is not known until the cycle runs, but the COLLIDING SHAPE
+// is visible at write time, and the write is the cheapest moment to say so.
+export async function siblingDestinations(folder, relativePath) {
+    const dir = path.dirname(path.join(folder, relativePath))
+    const base = path.basename(relativePath, path.extname(relativePath))
+    try {
+        const entries = await readdir(dir, { withFileTypes: true })
+        return entries
+            .filter(e => e.isFile()
+                && path.basename(e.name, path.extname(e.name)) === base
+                && e.name !== path.basename(relativePath))
+            .map(e => ({
+                path: path.join(path.dirname(relativePath), e.name),
+                note: 'same name, different extension — may render to the same destination',
+            }))
+    } catch {
+        return []
+    }
+}
+
+// The checksum of a file, or null when there is nothing there. Not an error
+// path: "does not exist yet" is the normal case for a create.
+async function fileChecksum(uri) {
+    try {
+        return await checksum(uri)
+    } catch {
+        return null
+    }
+}
+
+// The catalog entity written from this file, when there is one.
+async function findEntityAtUri(uri) {
+    if (!uri) return null
+    const matches = await findEntities({ uri })
+    return matches?.[0] ?? null
+}
+
+// Resolve a catalog id to the (collection, relativePath) pair a write needs.
+//
+// Taken from the entity rather than by splitting the id: the id prefix is
+// `idPrefix ?? '/' + collection` and the extension may have been stripped, so
+// splitting on the first segment is a guess that is usually right and
+// silently wrong for any source configured either way.
+export async function locateEntityFile(id) {
+    const entity = await readEntity({ id })
+    if (!entity) return { error: `No entity with id ${id}.` }
+    if (!entity.collection) {
+        return { error: `Entity ${id} has no collection, so its file location cannot be derived.` }
+    }
+    let folder
+    try {
+        folder = useCollection(runtime, entity.collection).folder
+    } catch (err) {
+        return { error: `Entity ${id} is in collection ${entity.collection}, which has no folder: ${err.message}` }
+    }
+    if (!entity.uri) {
+        return { error: `Entity ${id} has no uri — it is synthetic (emitted by a plugin, not read from a file) `
+            + 'and has no file to rewrite.' }
+    }
+    const relativePath = path.relative(folder, entity.uri)
+    if (!relativePath || relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+        return { error: `Entity ${id} lives at ${entity.uri}, outside its collection folder ${folder}.` }
+    }
+    return { collection: entity.collection, relativePath }
+}
+
+// Create or overwrite a source file inside a collection.
+//
+// Takes either `id` (an existing entity) or `collection` + `relativePath`.
+// `content` is the COMPLETE file: anything omitted is deleted.
+//
+// Never throws for an expected outcome. A refusal — a bad id, a path that
+// escapes the collection, a checksum that no longer matches — comes back as
+// `{ ok: false, refused }` with the facts needed to retry, because those are
+// answers rather than faults.
+//
+//   dryRun      write nothing; report what the write would touch
+//   ifChecksum  only write if the file's current DISK checksum equals this
+//   awaitCycle  resolve once the cycle that picks the write up has finished,
+//               with its build report attached
+export async function writeEntitySource({
+    id,
+    collection,
+    relativePath,
+    content = '',
+    ifChecksum,
+    dryRun = false,
+    awaitCycle = false,
+} = {}) {
+    if (id) {
+        const located = await locateEntityFile(id)
+        if (located.error) return { ok: false, refused: 'unresolvable-id', error: located.error }
+        // An explicit pair still wins if a caller passes both, but disagreeing
+        // with the id is a mistake worth refusing rather than silently
+        // resolving one way.
+        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)
+        // Containment before anything reads or writes. A relative path that
+        // escapes the collection must not even be STATTED — reporting a
+        // checksum for /etc/passwd is a disclosure on its own.
+        uri = handle.resolveWithin(relativePath)
+    } catch (err) {
+        return { ok: false, refused: 'invalid-target', collection, relativePath, error: err.message }
+    }
+
+    // Everything a caller should know BEFORE the bytes move. Computed for the
+    // dry run and the real write alike, so the preview and the thing it
+    // previews cannot disagree.
+    const existing = id ? await readEntity({ id }) : await findEntityAtUri(uri)
+    const onDisk = await readEntityContent({ uri }, { reload: true })
+    const advisories = contentAdvisories(existing, typeof onDisk.content === 'string' ? onDisk.content : null)
+
+    if (dryRun) {
+        const wouldAffect = existing?.id ? (runtime.manifest?.affectedBy?.(existing) ?? []) : []
+        const touched = new Set(wouldAffect.map(a => a.destination))
+        return {
+            ok: true, dryRun: true, collection, relativePath,
+            id: existing?.id ?? null,
+            exists: existing != null,
+            currentChecksum: await fileChecksum(uri),
+            advisories,
+            warning: advisoryWarning(advisories),
+            wouldAffect,
+            wouldAffectCount: wouldAffect.length,
+            siblingDestinations: await siblingDestinations(handle.folder, relativePath),
+            // Collisions ALREADY standing at the outputs this write would
+            // touch. A write cannot be blamed for them, but re-rendering into
+            // one is how the wrong half of a contested destination wins.
+            collisionsAtAffected: (runtime.manifest?.collisions?.() ?? [])
+                .filter(c => touched.has(c.destination)),
+            note: existing?.id
+                ? 'Destinations are computed with the engine\'s own skip rule, so they match what a real cycle '
+                    + 'would do — EXCEPT for changes to the entity\'s own frontmatter, which is parsed during '
+                    + 'import and can move its destination.'
+                : 'This file is not in the catalog yet, so nothing depends on it and there is no blast radius '
+                    + 'to report.',
+        }
+    }
+
+    // Checked immediately before the write. Not a lock — a writer that lands
+    // between the check and the write still wins — but it closes the window
+    // that matters in practice: read, think, write back a whole file built
+    // from a copy that is now stale.
+    const before = await fileChecksum(uri)
+    if (ifChecksum !== undefined && ifChecksum !== before) {
+        return {
+            ok: false,
+            refused: 'checksum-mismatch',
+            collection, relativePath,
+            expectedChecksum: ifChecksum,
+            currentChecksum: before,
+            hint: before === null
+                ? 'The file does not exist. Omit ifChecksum to create it.'
+                : 'The file on disk changed since you read it. Re-read it for the CONTENT, re-apply your change, '
+                    + 'and retry with `currentChecksum` from THIS response.',
+        }
+    }
+
+    const cycleId = nextCycleId()
+    await handle.write(relativePath, content)
+
+    const result = {
+        ok: true, collection, relativePath,
+        checksum: await fileChecksum(uri),
+        bytes: Buffer.byteLength(content),
+        cycleId,
+        siblingDestinations: await siblingDestinations(handle.folder, relativePath),
+    }
+    // Echoed on the way out, not only on read. A caller that never read the
+    // file — or read past the header — is exactly the one that needs telling,
+    // and telling it after the write still names what to check before deploy.
+    if (advisories.length) {
+        result.advisories = advisories
+        result.warning = advisoryWarning(advisories)
+    }
+    if (awaitCycle) result.report = await whenCycleCompletes(cycleId)
+    return result
+}