mikser-io 9.27.0 → 9.30.0

package/docs/api-reference.md

@@ -495,13 +495,28 @@ The engine substrate is a single sqlite file at
 that need their own persistence reach it through these two helpers —
 never by opening a second file.
 
-### `registerSchema(name, sqlScript)`
+### `registerSchema(name, sqlScript, { durable } = {})`
 
 Register a CREATE-TABLE-IF-NOT-EXISTS SQL block. All registered schemas
 are applied during `onLoaded`, after the engine's own tables
 (`mikser_entities`, `mikser_refs`, `mikser_snapshots`, `mikser_journal`,
 `mikser_meta`) and before any plugin's `onLoaded` runs.
 
+**`durable`** (default `false`) — keep these tables when the cache is
+wiped. The engine wipes on a schema-version change (any upgrade) and on a
+config-checksum change (any deploy that edits `mikser.config.js`), because
+per ADR-0002 the files are the source of truth and the database is derived.
+That holds for anything rebuildable and fails for anything that is not: an
+OAuth client registration, a refresh token, a received form submission
+cannot be recreated from the working folder, and losing them is silent —
+the first sign is a user being asked to sign in again after an unrelated
+deploy.
+
+Mark those `durable: true` and the wipe drops every other table instead of
+deleting the database file. Leave it off for anything you can rebuild:
+stale derived rows surviving an upgrade is the failure the wipe exists to
+prevent.
+
 ```js
 registerSchema('my_plugin_data', `
   CREATE TABLE IF NOT EXISTS my_plugin_data (

package/docs/diagnostics.md

@@ -19,6 +19,9 @@ engine source, the entry point is missing and belongs on this page.
 | What depends on this entity? | [`runtime.refs`](#runtimerefs) |
 | Which layout claimed this document, and why that one? | [`layouts.inspect()`](#layoutsinspect) |
 | Why does this page's output look stale? | [`runtime.manifest`](#runtimemanifest) |
+| Two files seem to fight over one output | [`--explain`](#--explain-entity), [`--verify`](#--verify) |
+| Which source file produced this built output? | [`runtime.manifest`](#runtimemanifest), `mikser_which` |
+| What would break if I changed this file? | [`runtime.manifest`](#runtimemanifest) `affectedBy` |
 | Did my schema validate anything at all? | [`schemas.names()`](#schemasnames--schemaslookup) |
 
 ## Command line
@@ -56,6 +59,20 @@ rendered    2026-08-22 21:07:52   → /page-a.html   [STALE: input hash moved si
 A snapshot written before per-input recording says so rather than
 guessing.
 
+When another entity renders to the same destination, that leads the
+verdict and the hash reasoning follows it:
+
+```
+CONTESTED — /bg/index.html is also claimed by /documents/bg/index.md.
+Whichever renders last wins and the other output is discarded; the
+input-hash reasoning below describes this entity only.
+```
+
+The full list is under `competingDestinations` in `--json` form. The
+hash reasoning on its own is true and useless here: "would be SKIPPED,
+input hash unchanged" is correct about the entity you asked about and
+silent about its output being overwritten by someone else's.
+
 A destination whose **last render attempt threw** reads as such, rather
 than as current:
 
@@ -128,6 +145,11 @@ Five buckets, and the distinction between them is the point:
 | `errors` | the render ran and **threw** — with `id`, `destination`, `error`, `layout` |
 | `gated` | a count — the source was unchanged, so no render was ever scheduled |
 
+Each report also carries `cycleId`, `startedAt` and `finishedAt`. Under
+`--watch` two consecutive reports are otherwise indistinguishable, so
+"is this my edit's cycle or the one before it" has no answer without the
+id. A cold build is cycle 1.
+
 A failed render appears in `errors` and **not** in `rendered`: that bucket
 means the output moved, and a throw writes nothing. The previous good bytes
 stay on disk, which is what makes a failed render survivable — and also
@@ -227,6 +249,14 @@ instead of building. Four categories, and the split matters:
 | `Mismatched` | the file's bytes differ from the recorded `outputHash` | error |
 | `No hash` | a snapshot with no recorded hash — nothing to compare | warning |
 | `Orphan` | a file on disk that no snapshot claims | warning |
+| `Collision` | two or more entities record snapshots for the same destination | warning |
+
+`Collision` is the one that does not show up as drift. Every render
+hashes the file *after* writing it, so when two entities write the same
+path the loser records the winner's bytes and both snapshots agree with
+disk — missing, mismatched and orphaned are all empty and the output is
+still wrong. It is reported by shape rather than by comparison, which is
+why it is here and not in the three categories above.
 
 Exit codes make it usable as a CI gate directly: `2` if anything is
 missing or mismatched, `1` if only warnings, `0` when clean, and `2` when
@@ -269,7 +299,16 @@ an SDK, or an agent speaking MCP actually has.
 
 **MCP** — `mikser_explain`, `mikser_build_report`, `mikser_verify`,
 alongside the existing `mikser_refs_*`, `mikser_layouts_inspect` and the
-`mikser://logs/recent` resource.
+`mikser://logs/recent` resource. Four more answer the questions a shell
+would otherwise be needed for: `mikser_search` finds a string across
+entity meta, source files and — with `in: ["output"]` — the built files,
+reporting occurrences per destination; `mikser_read_output` reads the
+bytes currently on disk for a destination, which is a different question
+from what the catalog or the manifest says should be there;
+`mikser_which` goes the other way, from a built destination back to the
+source that produced it and the line that defines a given selector; and
+`mikser_update_entity({ dryRun: true })` reports the blast radius of an
+edit before making it.
 
 **REST** — on the `api` plugin, gated on their own `diagnostics`
 operation:
@@ -398,7 +437,11 @@ What was rendered and whether it needs redoing.
 | `skipDecision(entity, …)` | `{ skip, reason }` — the same reason `--json` reports |
 | `recordedHashes()` | the dep-hashes dependents last saw |
 | `queryAffected(mutated)` | which query-dependent snapshots this mutation hits |
-| `verify({outputFolder})` | `{ missing, mismatched, unverifiable, orphaned }` — what `--verify` reports; pure, no mutations |
+| `snapshotsAt(destination)` | every snapshot claiming a destination — the reverse of `snapshotsFor`, and the way back from a built file to what produced it |
+| `affectedBy(entity)` | which destinations would re-render if this entity changed, each with the same `reason` the build report uses |
+| `verify({outputFolder})` | `{ verdict, missing, mismatched, unverifiable, orphaned, collisions }` — what `--verify` reports; pure, no mutations |
+| `collisions()` | destinations claimed by more than one entity, with the ids claiming each |
+| `writerOf(destination, outputHash)` | which of several claimants wrote the bytes now on disk, when the hashes can tell them apart |
 | `size()` | snapshot count |
 
 `snapshotsFor(id)` exists because an entity can render to several
@@ -406,6 +449,14 @@ destinations and a caller asking "what happened to this?" does not know
 them in advance — which is exactly the position you are in when a page
 did not change and you want to know why.
 
+`affectedBy(entity)` answers the same question one step earlier: *before*
+editing a shared file, which outputs does this reach? It runs the real
+`skipDecision` against each candidate rather than reimplementing the
+rule, so the preview and the cycle it previews cannot disagree. What it
+cannot model is how the entity's own frontmatter would change — that is
+parsed during import, so an edit that moves `meta.layout` moves the
+destination too, and this does not see it.
+
 ### `layouts.inspect()`
 
 Exposed by `mikser-io-layouts` at `runtime.options.layouts.inspect(id)`.

package/package.json

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

package/src/auth.js

@@ -112,6 +112,11 @@ export function reachabilityOf({ auth, token, allowRemote } = {}) {
 //     loopback, or allowRemote      → allow
 //     otherwise                     → 403
 //
+// A verifier may refine the "presented, invalid" case through an optional
+// `rejectionFor(req)` returning `{ status, code, description }` — see the
+// call site. It can only narrow a denial that already happened; there is no
+// return value from it that turns a rejection into an acceptance.
+//
 // `trustLoopback: true` restores the older mikser behaviour where a
 // token-gated endpoint stayed open to localhost. It exists so the api and
 // mcp plugins can keep their documented semantics for a plain `token:`
@@ -123,10 +128,30 @@ export async function authorize(req, verifier, { allowRemote = false, trustLoopb
         const result = await verifier.verify(req)
         if (result) return { ok: true, principal: result }
         if (result === false) {
-            return { ok: false, status: 401, reason: 'invalid',
-                     error: 'Invalid credential' }
+            // A rejected credential is not one thing. An EXPIRED token means
+            // "exchange your refresh token and retry" — a client does that
+            // silently. A token whose subject lacks the capability means
+            // "refreshing will not help", and a client that refreshes on it
+            // loops. Told apart only by the verifier, which is the only thing
+            // that looked at the credential, so it gets to refine the answer.
+            //
+            // Absent (every verifier before this existed), the answer is
+            // today's: 401 invalid_token, which is right for the common case
+            // and is what a client needs in order to refresh at all.
+            const refined = verifier.rejectionFor?.(req)
+            return {
+                ok: false,
+                status: refined?.status ?? 401,
+                reason: 'invalid',
+                code: refined?.code ?? 'invalid_token',
+                description: refined?.description,
+                error: refined?.description ?? 'Invalid credential',
+            }
         }
-        // Nothing presented.
+        // Nothing presented. No `code`: RFC 6750 §3.1 says a challenge to a
+        // request that carried no credential omits `error` entirely, and the
+        // omission is the signal — it is how a client tells "you have never
+        // authenticated here" from "the token you hold went stale".
         if (trustLoopback && local) return { ok: true, principal: { subject: 'loopback' } }
         return { ok: false, status: 401, reason: 'missing',
                  error: 'Authentication required' }
@@ -153,7 +178,12 @@ export function requireAuth(verifier, options = {}) {
             req.principal = outcome.principal
             return next()
         }
-        if (outcome.status === 401) verifier?.challenge?.(req, res)
+        // 403 carries a challenge too: RFC 6750 §3.1 puts insufficient_scope
+        // there, and a client that only reads the header on a 401 is exactly
+        // the client that cannot tell the two apart.
+        if (outcome.status === 401 || outcome.status === 403) {
+            verifier?.challenge?.(req, res, outcome)
+        }
         res.status(outcome.status).json({ error: outcome.error })
     }
 }
@@ -202,12 +232,24 @@ export function anyOf(...verifiers) {
             return rejected ? false : null
         },
 
+        // Whichever member actually judged the credential gets to say why it
+        // failed. Without forwarding this, composing a static token with an
+        // OAuth verifier silently downgrades every expiry to a bare 401 and
+        // the refresh signal is lost precisely on the surfaces that have one.
+        rejectionFor(req) {
+            for (const verifier of list) {
+                const refined = verifier.rejectionFor?.(req)
+                if (refined) return refined
+            }
+            return undefined
+        },
+
         // Challenge with the verifier that can actually be satisfied
         // interactively — pointing a browser at "Bearer" when the real
         // option is OAuth discovery helps nobody.
-        challenge(req, res) {
+        challenge(req, res, outcome) {
             const chooser = discovering ?? list.find(v => v.challenge)
-            chooser?.challenge?.(req, res)
+            chooser?.challenge?.(req, res, outcome)
         },
     }
 }

package/src/database/index.js

@@ -103,7 +103,26 @@ let db = null
 // duplicate detection. Same name twice = the later registration wins
 // (with a warning). Convention: `<owner>` matching the table prefix
 // (`catalog`, `manifest`, `vector`, etc.).
-export function registerSchema(name, sqlScript) {
+// Table names a schema script creates. Used to decide what a cache wipe
+// must leave alone — the registry knows schema NAMES, and the wipe works in
+// tables.
+// A registered schema is either { sql, durable } or, from an external
+// caller of createSqliteDatabase, the bare SQL string that shape replaced.
+// Both are supported: the argument is public API and a plugin or test
+// passing a Map of strings predates the durability flag.
+function schemaEntry(value) {
+    return typeof value === 'string' ? { sql: value, durable: false } : value
+}
+
+function tableNamesFrom(sqlScript) {
+    const names = []
+    const re = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"'\[]?([A-Za-z_][\w$]*)/gi
+    let m
+    while ((m = re.exec(sqlScript))) names.push(m[1])
+    return names
+}
+
+export function registerSchema(name, sqlScript, { durable = false } = {}) {
     if (typeof name !== 'string' || !name.length) {
         throw new Error('registerSchema: name must be a non-empty string')
     }
@@ -117,7 +136,7 @@ export function registerSchema(name, sqlScript) {
             useLogger().warn('registerSchema: "%s" already registered, overwriting', name)
         } catch { /* logger may not exist yet at module-import time */ }
     }
-    schemas.set(name, sqlScript)
+    schemas.set(name, { sql: sqlScript, durable })
 
     // Lazy-apply: if the database is already open, run the script
     // against the live handle. Idempotent CREATE statements make this
@@ -295,15 +314,50 @@ export function createSqliteDatabase({
                     recorded, version,
                 )
             }
-            handle.close()
-            handle = null
+            // What must survive. A wipe exists because the cache is
+            // DERIVED — ADR-0002, the files are the source of truth, so
+            // throwing it away costs a rebuild and nothing else. That
+            // reasoning does not reach a table holding data no file can
+            // reproduce: an OAuth client registration, a refresh token, a
+            // form submission. Deleting the database file takes those with
+            // it, and the operator's first sign that it happened is being
+            // asked to authorize again.
+            //
+            // So a schema registered `durable` is kept and everything else
+            // goes. mikser_meta stays too — its stamps are rewritten a few
+            // lines down, and dropping it would only mean recreating it.
+            const durableTables = new Set(['mikser_meta'])
+            for (const value of schemas.values()) {
+                const { sql, durable } = schemaEntry(value)
+                if (durable) for (const t of tableNamesFrom(sql)) durableTables.add(t)
+            }
+
+            if (durableTables.size > 1 && dbPath !== ':memory:') {
+                // Drop table by table rather than unlinking, so the durable
+                // ones keep their rows. Foreign keys off for the duration:
+                // a cache table may reference another and drop order here is
+                // whatever sqlite_master returns.
+                const tables = handle
+                    .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+                    .all()
+                handle.exec('PRAGMA foreign_keys = OFF')
+                for (const { name: table } of tables) {
+                    if (durableTables.has(table)) continue
+                    handle.exec(`DROP TABLE IF EXISTS "${table}"`)
+                }
+                handle.exec('PRAGMA foreign_keys = ON')
+                logger?.debug('Cache wiped, %d durable table(s) preserved', durableTables.size - 1)
+            } else {
+                handle.close()
+                handle = null
 
-            if (dbPath !== ':memory:') {
-                // sqlite WAL leaves -wal and -shm sidecar files. Remove
-                // them along with the main file so the next open starts
-                // from a guaranteed-clean slate.
-                for (const suffix of ['', '-wal', '-shm']) {
-                    try { unlinkSync(dbPath + suffix) } catch { /* file may not exist */ }
+                if (dbPath !== ':memory:') {
+                    // sqlite WAL leaves -wal and -shm sidecar files. Remove
+                    // them along with the main file so the next open starts
+                    // from a guaranteed-clean slate.
+                    for (const suffix of ['', '-wal', '-shm']) {
+                        try { unlinkSync(dbPath + suffix) } catch { /* file may not exist */ }
+                    }
                 }
             }
 
@@ -311,8 +365,10 @@ export function createSqliteDatabase({
             // which is the right shape for a config change too: what the
             // provisioners see is an empty-state database either way.
             upgradedFromVersion = recorded ?? 'config'
-            handle = new Database(dbPath)
-            setupConnection()
+            if (!handle) {
+                handle = new Database(dbPath)
+                setupConnection()
+            }
         }
         const stmtStamp = handle.prepare('INSERT OR REPLACE INTO mikser_meta (key, value) VALUES (?, ?)')
         stmtStamp.run('schema_version', version)
@@ -354,7 +410,8 @@ export function createSqliteDatabase({
 
         // Apply each subsystem's registered schema script. Idempotent
         // CREATE statements mean replay-safe across opens.
-        for (const [name, sqlScript] of schemas) {
+        for (const [name, value] of schemas) {
+            const { sql: sqlScript } = schemaEntry(value)
             try {
                 handle.exec(sqlScript)
                 logger?.debug('Database schema applied: %s', name)

package/src/engine.js

@@ -10,7 +10,7 @@ import { useJournal, updateEntry } from './journal.js'
 import { globby } from 'globby'
 import { OPERATION, TASKS } from './constants.js'
 import { changeExtension, formatErrorContext, projectMeta, lookupKeys } from './utils.js'
-import { reportRendered, reportSkipped, reportError, renderErrorCount, emitReport } from './report.js'
+import { reportRendered, reportSkipped, reportError, reportWarning, renderErrorCount, emitReport, finishCycle } from './report.js'
 import render from './render.js'
 import postprocess, { loadPlugin as loadPostPlugin } from './postprocess.js'
 import map from 'p-map'
@@ -253,35 +253,40 @@ export async function setup(options) {
                 logger.error('Verify: no manifest available — nothing to check against')
                 process.exit(2)
             }
-            const diff = await runtime.manifest.verify()
-            const { missing, mismatched, unverifiable, orphaned } = diff
-
+            const { verdict, missing, mismatched, unverifiable, orphaned, collisions } =
+                await runtime.manifest.verify()
             const total = runtime.manifest.size()
-            const errors = missing.length + mismatched.length
-            const warnings = orphaned.length + unverifiable.length
 
-            for (const e of missing)     logger.error('Missing:    %s (entity %s)', e.destination, e.id)
-            for (const e of mismatched)  logger.error('Mismatched: %s (entity %s)', e.destination, e.id)
+            for (const e of missing)      logger.error('Missing:    %s (entity %s)', e.destination, e.id)
+            for (const e of mismatched)   logger.error('Mismatched: %s (entity %s)%s', e.destination, e.id,
+                e.writtenBy ? ` — the bytes on disk are ${e.writtenBy}'s` : '')
             for (const e of unverifiable) logger.warn('No hash:    %s (entity %s)', e.destination, e.id)
-            for (const e of orphaned)    logger.warn('Orphan:     %s', e.path)
+            for (const e of orphaned)     logger.warn('Orphan:     %s', e.path)
+            // Named per destination: "two entities write here" is only
+            // actionable if you know which two.
+            for (const c of collisions)   logger.warn('Collision:  %s ← %s', c.destination, c.entities.join(', '))
 
             // Level picked from the verdict, because the level IS the marker
             // in pino-pretty's messageFormat: notice renders 🟢, warn 🟡,
             // error 🔴. A fixed `notice` prints a green tick next to the word
             // FAIL, which reads as success at a glance even though the exit
             // code is right.
-            const verdict = errors > 0 ? 'FAIL' : (warnings > 0 ? 'WARN' : 'OK')
-            const report = errors > 0 ? logger.error : (warnings > 0 ? logger.warn : logger.notice)
+            const report = verdict === 'FAIL' ? logger.error : verdict === 'WARN' ? logger.warn : logger.notice
             report.call(logger,
-                'Verify %s: %d snapshots, %d missing, %d mismatched, %d unverifiable, %d orphaned',
-                verdict, total, missing.length, mismatched.length, unverifiable.length, orphaned.length)
-            process.exit(errors > 0 ? 2 : (warnings > 0 ? 1 : 0))
+                'Verify %s: %d snapshots, %d missing, %d mismatched, %d unverifiable, %d orphaned, %d collisions',
+                verdict, total, missing.length, mismatched.length, unverifiable.length, orphaned.length, collisions.length)
+            process.exit(verdict === 'FAIL' ? 2 : verdict === 'WARN' ? 1 : 0)
         }
     })
 
     onRender(async (signal) => {
         const logger = useLogger()
         const renderJobs = new Set()
+        // destination → the entity ids that actually rendered to it this
+        // cycle. Recorded past the skip gate rather than alongside renderJobs
+        // so it holds renders that ran, which is what makes "one overwrote
+        // the other" a true statement rather than a guess about two claims.
+        const renderedTo = new Map()
 
         // Collect this cycle's mutated entity ids/hrefs/entities so the
         // manifest skip check can re-render anything whose dependencies
@@ -374,6 +379,10 @@ export async function setup(options) {
                     logger.debug('Manifest skip: %s → %s', entity.name || entity.id, entity.destination)
                     return
                 }
+                if (entity.destination) {
+                    if (!renderedTo.has(entity.destination)) renderedTo.set(entity.destination, new Set())
+                    renderedTo.get(entity.destination).add(entity.id)
+                }
                 // Reported on the way OUT, not here: `rendered` means the
                 // output moved, and a render that throws writes nothing. The
                 // decision is carried down to the success path so the reason
@@ -575,6 +584,27 @@ export async function setup(options) {
         renderJobs.size && logger.info('Rendered: %d', renderJobs.size - skipped - failed)
         skipped && logger.info('Manifest skipped: %d', skipped)
         failed && logger.error('Render errors: %d', failed)
+
+        // Two entities writing one destination in the same cycle: one
+        // silently overwrote the other, and every other signal reads clean.
+        // Reported per cycle rather than only by --verify because this is
+        // the moment it happened, and because a build that discards half its
+        // output must not report warnings: 0.
+        //
+        // Derived from the destinations THIS cycle rendered, so an
+        // established collision the operator already knows about does not
+        // re-warn on every unrelated build; --verify is where the standing
+        // state lives.
+        for (const [destination, ids] of renderedTo) {
+            if (ids.size < 2) continue
+            const entities = [...ids].sort()
+            reportWarning('destination-collision', { destination, entities })
+            logger.warn(
+                'Destination collision: %s written by %d entities in this cycle (%s). '
+                + 'One overwrote the other — whichever rendered last wins.',
+                destination, entities.length, entities.join(', '),
+            )
+        }
     })
 
     onBeforePostprocess(async (signal) => {
@@ -801,6 +831,11 @@ export async function setup(options) {
                 }
             }
         }
+        // Close the cycle: stamp it and file it in the history, so a caller
+        // that asked "tell me about cycle N" gets an answer after N ends
+        // rather than only while it is the current one.
+        finishCycle()
+
         // A cycle with failed renders is not a completed build, and the word
         // people read is this one.
         const failed = renderErrorCount()

package/src/explain.js

@@ -85,6 +85,17 @@ function queryCount(counts, filter) {
     return { matched: hit.count, ...(hit.count === 1 && hit.sample ? { sample: hit.sample } : {}) }
 }
 
+// A destination two entities claim outranks anything the hashes say. The
+// hash reasoning would be true AND useless: "would be SKIPPED, input hash
+// unchanged" is correct about this entity and silent about the fact that
+// its output is being overwritten by someone else's.
+function contestedVerdict(competing) {
+    if (!competing.length) return null
+    const parts = competing.map(c => `${c.destination} is also claimed by ${c.entities.join(', ')}`)
+    return `CONTESTED — ${parts.join('; ')}. Whichever renders last wins and the other output is discarded; `
+        + 'the input-hash reasoning below describes this entity only.'
+}
+
 // The verdict line names what moved when it can. That line is the one
 // people read, so "the input hash differs" there is the answer stopping one
 // step short of useful.
@@ -252,7 +263,8 @@ export async function explain(reference) {
                     }),
         })),
         // What a plain build would do next, stated plainly.
-        verdict: source?.error === 'file is gone'
+        verdict: contestedVerdict(competingFor(snapshots, entity.id))
+            ?? (source?.error === 'file is gone'
             ? 'source file is gone — a build would DELETE this entity and unlink its output'
             : source?.differs
                 ? 'source differs from the catalog — a build would re-import it first, then re-render. '
@@ -264,11 +276,32 @@ export async function explain(reference) {
                   + `(${failedSnapshots[0].error})`
             : snapshots.some(s => s.inputHash !== currentHash)
                 ? renderVerdict(snapshots, currentHash, currentParts)
-                : 'would be SKIPPED — input hash unchanged. A dependency in refClosure changing is the only other thing that would re-render it.',
+                : 'would be SKIPPED — input hash unchanged. A dependency in refClosure changing is the only other thing that would re-render it.'),
         lookupKeys: lookupKeys(entity),
+        // Other entities rendering to the same path as this one.
+        //
+        // The failure this makes visible: an empty stub and a real page both
+        // claiming /bg/index.html. Whichever renders last wins, the other's
+        // output is discarded, and nothing else says so — not the build
+        // (green), not verify (each render hashes the file after writing, so
+        // the loser records the winner's bytes and both snapshots agree with
+        // disk), and not this report, which showed the destination and a
+        // clean "would be SKIPPED".
+        competingDestinations: competingFor(snapshots, entity.id),
     }
 }
 
+// Entities other than `id` whose snapshots claim the same destinations.
+function competingFor(snapshots, id) {
+    const mine = new Set(snapshots.map(s => s.destination).filter(Boolean))
+    if (!mine.size) return []
+    const all = runtime.manifest?.collisions?.() ?? []
+    return all
+        .filter(c => mine.has(c.destination))
+        .map(c => ({ destination: c.destination, entities: c.entities.filter(e => e !== id) }))
+        .filter(c => c.entities.length)
+}
+
 // Human-readable rendering. Deliberately aligned columns rather than prose:
 // the point is to be scanned, and to be diffable between two runs.
 export function formatExplain(report) {

package/src/manifest.js

@@ -56,7 +56,7 @@ import { useLogger } from './engine.js'
 import { onLoaded, onFinalize } from './lifecycle.js'
 import { useJournal } from './journal.js'
 import { OPERATION } from './constants.js'
-import { extractRefs, inputHashOf, inputPartsOf, diffInputParts } from './utils.js'
+import { extractRefs, inputHashOf, inputPartsOf, diffInputParts, lookupKeys } from './utils.js'
 import { filterKey } from './track.js'
 import { findById } from './catalog.js'
 import { useDatabase, registerSchema } from './database/index.js'
@@ -284,6 +284,25 @@ async function hashOutputFile(destination) {
 export function createManifest(db) {
     if (!db) throw new Error('createManifest: db is required')
 
+    const stmtCollisions = db.prepare(`
+        SELECT destination, count(*) AS n, group_concat(id) AS ids
+        FROM mikser_snapshots
+        GROUP BY destination HAVING n > 1
+    `)
+    const stmtClaimants = db.prepare(`
+        SELECT id, outputHash FROM mikser_snapshots WHERE destination = ?
+    `)
+    const stmtSelectByDestination = db.prepare(`
+        SELECT id FROM mikser_snapshots WHERE destination = ?
+    `)
+    const stmtLookupByDestination = db.prepare(`
+        SELECT id, destination, inputHash, inputParts, outputHash, refClosure, renderedAt, parent
+        FROM mikser_snapshots WHERE destination = ?
+    `)
+    const stmtDeleteByDestination = db.prepare(`
+        DELETE FROM mikser_snapshots WHERE destination = ?
+    `)
+
     const stmtRecordFailure = db.prepare(`
         INSERT INTO mikser_failures
             (id, destination, error, context, firstFailedAt, lastFailedAt, attempts)
@@ -377,6 +396,28 @@ export function createManifest(db) {
         WHERE refClosure LIKE '%"kind":"query"%'
     `)
 
+    // Snapshots holding a non-query edge that names any of the given keys,
+    // by the name asked for OR by the entity it bound to. Both, for the same
+    // reason skipDecision reads both — a name survives a rename only through
+    // the binding, and a forward edge to a page that does not exist yet has
+    // only the name.
+    //
+    // A prefilter, not the answer: it narrows a corpus-wide walk to the
+    // handful of snapshots that could possibly care, and the real
+    // skipDecision then judges each one.
+    const edgeCandidates = (keys) => {
+        if (!keys.length) return []
+        const holes = keys.map(() => '?').join(',')
+        return db.prepare(`
+            SELECT DISTINCT s.id AS id, s.destination AS destination
+            FROM mikser_snapshots s, json_each(s.refClosure) j
+            WHERE s.refClosure IS NOT NULL
+              AND json_extract(j.value, '$.kind') != 'query'
+              AND (json_extract(j.value, '$.target')   IN (${holes})
+                OR json_extract(j.value, '$.targetId') IN (${holes}))
+        `).all(...keys, ...keys)
+    }
+
     const manifest = {
         // Look up a previously-recorded entry by entity (or by an
         // object with `{id, destination}`). Returns the snapshot, or
@@ -399,6 +440,78 @@ export function createManifest(db) {
             return stmtLookupById.all(id).map(rowToSnap)
         },
 
+        // Every snapshot that claims a destination — the reverse of
+        // snapshotsFor, and the entry point for "what produced this file?".
+        // More than one means a collision; see collisions().
+        snapshotsAt(destination) {
+            if (!destination) return []
+            return stmtLookupByDestination.all(destination).map(rowToSnap)
+        },
+
+        // Which destinations would re-render if this entity changed.
+        //
+        // Answered by running the REAL skipDecision against each candidate,
+        // with the mutation maps the render loop would build for exactly this
+        // one entity. A second implementation of the invalidation rule would
+        // be a preview that disagrees with the cycle it is previewing, which
+        // is worse than no preview: it would be trusted.
+        //
+        // What it cannot model, and says so at its caller: how the entity's
+        // OWN meta would change. Frontmatter is parsed during import, not
+        // here, so a change that alters meta.layout (and therefore the
+        // destination itself) is outside what this can see. Its own snapshots
+        // are reported as affected regardless, which is the safe direction.
+        affectedBy(entity) {
+            if (!entity?.id) return []
+            const lang = entity?.meta?.lang ?? null
+            const hash = inputHashOf(entity)
+            const keys = lookupKeys(entity)
+            const mutatedRefs = new Map(keys.map(key => [key, new Set([lang])]))
+            const currentHashes = new Map(keys.map(key => [key, hash]))
+            const mutatedEntities = new Map([[entity.id, entity]])
+
+            // Three ways a snapshot can care, unioned before judging so a
+            // snapshot reachable by two of them is judged once.
+            const candidates = new Map()
+            const consider = (id, destination) => {
+                if (!id || !destination) return
+                candidates.set(`${id}\u0000${destination}`, { id, destination })
+            }
+            for (const snap of this.snapshotsFor(entity.id)) consider(snap.id, snap.destination)
+            for (const row of edgeCandidates(keys)) consider(row.id, row.destination)
+            for (const id of this.queryAffected(mutatedEntities)) {
+                for (const snap of this.snapshotsFor(id)) consider(snap.id, snap.destination)
+            }
+
+            const affected = []
+            for (const { id, destination } of candidates.values()) {
+                // Its own renders: the premise of the question is that this
+                // entity changed, so asking skipDecision — which compares the
+                // hash of the entity as it stands NOW — would answer
+                // "unchanged" and hide the one destination the caller is
+                // certainly touching.
+                if (id === entity.id) {
+                    affected.push({ id, destination, reason: 'inputs-changed', why: 'this entity\'s own render' })
+                    continue
+                }
+                const dependent = findById(id)
+                if (!dependent) continue
+                const decision = this.skipDecision(
+                    { ...dependent, destination }, mutatedRefs, currentHashes, mutatedEntities)
+                if (decision.skip) continue
+                // The same provenance the build report carries. A bare list of
+                // destinations answers "how many" and not "why this one",
+                // which is the half that makes it checkable.
+                affected.push({
+                    id, destination, reason: decision.reason,
+                    ...(decision.changed?.length ? { changed: decision.changed } : {}),
+                    ...(decision.matched ? { matched: decision.matched } : {}),
+                    ...(decision.dependency ? { dependency: decision.dependency } : {}),
+                })
+            }
+            return affected
+        },
+
         // Should this render be skipped? See the original docstring in
         // the prior NDJSON-backed implementation — logic is unchanged,
         // backing storage is the only thing that changed.
@@ -610,6 +723,37 @@ export function createManifest(db) {
             stmtClearFailure.run(entity.id, entity.destination)
         },
 
+        // Destinations claimed by more than one entity.
+        //
+        // Two entities rendering to one path is always a bug — one silently
+        // overwrites the other — and it is invisible to every other check.
+        // Not to `verify`'s hash comparison in particular: each render
+        // records the hash of the file AFTER it wrote, so with concurrent
+        // renders the loser reads the winner's bytes and both snapshots
+        // agree with disk. Measured on the case this exists for: an empty
+        // stub and a real homepage both claiming /bg/index.html recorded the
+        // SAME outputHash, and verify reported OK.
+        //
+        // So it is detected structurally rather than by content: the
+        // manifest already knows both claimants because a snapshot is keyed
+        // (id, destination).
+        collisions() {
+            return stmtCollisions.all().map(row => ({
+                destination: row.destination,
+                entities: String(row.ids).split(',').filter(Boolean).sort(),
+            }))
+        },
+
+        // Which entity's recorded bytes are the ones on disk right now.
+        // Answers "who wrote this?" for a destination several entities
+        // claim, which is the question a mismatch leaves open.
+        writerOf(destination, outputHash) {
+            if (!destination || !outputHash) return null
+            const rows = stmtClaimants.all(destination)
+            const match = rows.find(r => r.outputHash === outputHash)
+            return match?.id ?? null
+        },
+
         // Every recorded failure for an entity, across destinations.
         failuresFor(id) {
             return id ? stmtFailuresFor.all(id) : []
@@ -821,8 +965,18 @@ export function createManifest(db) {
                 }
                 try {
                     const buf = await readFile(filePath)
-                    if (sha1(buf) !== snap.outputHash) {
-                        mismatched.push({ id: snap.id, destination: snap.destination })
+                    const actual = sha1(buf)
+                    if (actual !== snap.outputHash) {
+                        // Name who DID write the bytes that are there, when a
+                        // sibling snapshot for the same destination matches
+                        // them. "Mismatched" alone leaves the reader to work
+                        // out whether the file was edited by hand or lost a
+                        // race with another entity claiming the same path.
+                        mismatched.push({
+                            id: snap.id,
+                            destination: snap.destination,
+                            writtenBy: this.writerOf(snap.destination, actual),
+                        })
                     }
                 } catch {
                     missing.push({ id: snap.id, destination: snap.destination })
@@ -839,7 +993,29 @@ export function createManifest(db) {
                 if (claimed.has(rel)) continue
                 orphaned.push({ path: rel })
             }
-            return { missing, mismatched, unverifiable, orphaned }
+            // Reported alongside, not as a mismatch: two entities claiming one
+            // destination usually produces NO mismatch at all, because each
+            // render hashes the file after writing it and the loser reads the
+            // winner's bytes. Without this the whole situation is silent.
+            const collisions = this.collisions()
+            // One verdict, computed here, because three callers report it —
+            // the CLI's exit code, the api route and the MCP tool — and three
+            // copies of the rule would drift.
+            //
+            // A collision is a WARNING, not a failure: nothing is missing or
+            // corrupt, the bytes on disk are some entity's real render. What
+            // is wrong is that another entity's output was discarded, which
+            // the reader has to be told about but which does not mean the
+            // deploy is broken in the way a missing or altered file does.
+            // It is also pre-existing on any site that already has one, so
+            // failing the gate outright would break pipelines on upgrade for
+            // a condition that was always there.
+            const errors = missing.length + mismatched.length
+            const warnings = orphaned.length + unverifiable.length + collisions.length
+            return {
+                verdict: errors > 0 ? 'FAIL' : warnings > 0 ? 'WARN' : 'OK',
+                missing, mismatched, unverifiable, orphaned, collisions,
+            }
         },
 
         size() {
@@ -852,6 +1028,8 @@ export function createManifest(db) {
         _stmtSelectByIdOrParent: stmtSelectByIdOrParent,
         _stmtDeleteByIdOrParent: stmtDeleteByIdOrParent,
         _stmtSelectByParent:     stmtSelectByParent,
+        _stmtSelectByDestination: stmtSelectByDestination,
+        _stmtDeleteByDestination: stmtDeleteByDestination,
         _stmtDeleteByPK:         stmtDeleteByPK,
         _stmtUpsert:             stmtUpsert,
     }
@@ -961,8 +1139,54 @@ onFinalize(async () => {
         }
     }
 
+    // Everything whose snapshot this pass removes: deleted entities, their
+    // paginated children, and children dropped by a pagination shrink.
+    const goingAway = new Set(deleted)
+    for (const { id } of childrenToDelete) goingAway.add(id)
+    for (const parentId of deleted) {
+        for (const row of m._stmtSelectByParent.all(parentId)) goingAway.add(row.id)
+    }
+
     // 2d. Unlink stale output files (async, parallel-friendly).
+    //
+    // Never unlink a destination another entity still claims. Two entities
+    // can render to one path — an empty `index.md` beside the real
+    // `index.yml` — and deleting one of them was taking the shared output
+    // with it: the file vanished while the survivor's snapshot still said it
+    // was there, the survivor's own source had not changed so nothing
+    // re-rendered it, and --verify reported it missing.
+    //
+    // That made "resolve the collision by deleting the stub" delete the
+    // homepage, which is the opposite of what the operator asked for and the
+    // exact operation the new collision reporting invites.
     for (const { destination, reason } of filesToUnlink) {
+        // "Still claimed" means by something that SURVIVES this pass. The
+        // ids going away here are not just the deleted entities: pagination
+        // children staged above are removed too, and counting a child's own
+        // snapshot as a claimant would keep every shrunk page on disk
+        // forever.
+        const stillClaimed = m._stmtSelectByDestination.all(destination)
+            .filter(row => row.id !== undefined && !goingAway.has(row.id))
+        if (stillClaimed.length) {
+            // Keep the file — deleting a live page's output is worse than any
+            // staleness — but do NOT let the state go quiet. The bytes on
+            // disk were written by the entity that just went away, and the
+            // survivor's snapshot recorded that same hash (each render hashes
+            // the file after writing, so the loser recorded the winner's
+            // bytes). Left alone, verify would compare the survivor's
+            // snapshot against the deleted entity's output and report OK.
+            //
+            // Dropping the survivor's snapshot for this destination makes it
+            // an orphan — a file no snapshot claims, which is exactly what it
+            // is — so verify warns instead of blessing it, and the next time
+            // the survivor renders it is `never-rendered` rather than skipped.
+            m._stmtDeleteByDestination.run(destination)
+            logger.warn(
+                '%s: %s is also written by %s — keeping the file, but its bytes came from the '
+                + 'deleted entity. Re-render or --force to refresh it.',
+                reason, destination, stillClaimed.map(r => r.id).join(', '))
+            continue
+        }
         const filePath = path.join(runtime.options.outputFolder, destination)
         try {
             await unlink(filePath)

package/src/plugins/api.js

@@ -982,18 +982,14 @@ export function api(options = {}) {
                     if (!runtime.manifest?.verify) {
                         return res.status(503).json({ error: 'No manifest available — nothing to verify against' })
                     }
-                    const diff = await runtime.manifest.verify()
-                    const errors = diff.missing.length + diff.mismatched.length
-                    const warnings = diff.orphaned.length + diff.unverifiable.length
                     // 200 either way — the check ran and this is its answer. A
                     // CI gate reads `verdict`, which mirrors the CLI's exit
                     // vocabulary, rather than inferring from a status code that
-                    // would conflate "drift found" with "request failed".
-                    return res.json({
-                        verdict: errors > 0 ? 'FAIL' : warnings > 0 ? 'WARN' : 'OK',
-                        snapshots: runtime.manifest.size?.() ?? null,
-                        ...diff,
-                    })
+                    // would conflate "drift found" with "request failed". The
+                    // verdict comes from the manifest so this route cannot
+                    // disagree with the CLI about what counts as a failure.
+                    const diff = await runtime.manifest.verify()
+                    return res.json({ snapshots: runtime.manifest.size?.() ?? null, ...diff })
                 } catch (err) {
                     logger.error('Api verify error: %s', err.message)
                     return res.status(500).json({ error: err.message })

package/src/refs.js

@@ -85,6 +85,16 @@ export const REFS_SCHEMA = `
 `
 registerSchema('mikser_refs', REFS_SCHEMA)
 
+// json_tree's `fullkey` → the field path the ref index uses.
+// `$.meta.items[0].href` → `items[0].href`, and a quoted segment
+// (`$.meta."$author"`, which is how json_tree spells a key starting with
+// `$`) loses its quotes so both spellings compare equal.
+function normalizeMetaPath(fullkey) {
+    return String(fullkey)
+        .replace(/^\$\.meta\.?/, '')
+        .replace(/"([^"]*)"/g, '$1')
+}
+
 // Build the index handle over the provided sqlite database. Prepares
 // the SQL statements once at construction; subsequent reads/writes
 // reuse them.
@@ -100,6 +110,16 @@ export function createIndex(db) {
         SELECT source_id, field FROM mikser_refs
         WHERE target_ref = ? AND kind = 'ref'
     `)
+    // Any string value anywhere under an entity's meta that equals the
+    // target — including inside arrays, which is where nav and footer link
+    // lists live. json_tree walks the stored JSON, so no schema and no
+    // write-time indexing is involved.
+    const stmtInboundMetaValue = db.prepare(`
+        SELECT DISTINCT e.id AS id, j.fullkey AS field
+        FROM mikser_entities e, json_tree(e.data, '$.meta') j
+        WHERE j.type = 'text' AND j.value = ?
+    `)
+
     const stmtOutboundStatic = db.prepare(`
         SELECT field, target_ref FROM mikser_refs
         WHERE source_id = ? AND kind = 'ref'
@@ -196,9 +216,44 @@ export function createIndex(db) {
 
     // -- Read API ------------------------------------------------------
 
+    // Everything that points at `ref`, by BOTH mechanisms.
+    //
+    // The index holds `$`-keyed refs only, because those are the ones the
+    // engine resolves and invalidates on. But a site links to a page far
+    // more often with a plain string — `items: [{ label, href: '/about' }]`
+    // in a nav or footer document — and asking "what breaks if I delete
+    // this" got `count: 0` while two live pages linked to it. A silent miss
+    // is worse than no answer for that question.
+    //
+    // Plain values are found at READ time with json_tree over each entity's
+    // meta rather than indexed at write time: indexing every string in every
+    // meta would put the whole catalog in the edge table to serve a
+    // diagnostic, and the engine does not invalidate on plain strings
+    // anyway — which is itself worth knowing, and is why the two kinds stay
+    // labelled rather than merged.
     function inboundFor(ref) {
-        return stmtInboundStatic.all(ref)
-            .map(r => ({ id: r.source_id, field: r.field }))
+        const refs = stmtInboundStatic.all(ref)
+            .map(r => ({ id: r.source_id, field: r.field, kind: 'ref' }))
+        const seen = new Set(refs.map(r => `${r.id}|${r.field}`))
+        const hrefs = []
+        for (const row of stmtInboundMetaValue.all(ref)) {
+            const field = normalizeMetaPath(row.field)
+            // A `$`-keyed path is the ref index's territory by definition, and
+            // json_tree finds those values too — reporting them again as
+            // `href` would double-count every ref and mislabel it. Note that
+            // json_tree QUOTES a key beginning with `$` (`$.meta."$author"`),
+            // so this has to run after unquoting or the two spellings never
+            // meet and the dedup below misses.
+            if (field.split('.').some(seg => seg.startsWith('$'))) continue
+            // `meta.href` / `meta.url` at the top level are the entity's own
+            // ADDRESS, not a link to something else. Without this, asking
+            // what points at /about lists /documents/bg/about.md — the page
+            // itself — among the things that would break if it were deleted.
+            if (field === 'href' || field === 'url') continue
+            if (seen.has(`${row.id}|${field}`)) continue
+            hrefs.push({ id: row.id, field, kind: 'href' })
+        }
+        return [...refs, ...hrefs]
     }
 
     function outboundFor(sourceId) {
@@ -628,9 +683,17 @@ export function createRefs(db, prebuiltIndex = null) {
             }
             if (from === to) return { from, to, updated: [], failures: [] }
 
-            const entries = index.inboundFor(from)
+            // `$`-keyed refs only, deliberately. inboundFor also reports
+            // plain string matches now — a nav item's `href` — but writeEntity
+            // patches `$`-keyed values, and rewriting arbitrary meta strings
+            // through it is a file-mutating change nobody asked for. A plain
+            // href pointing at the old name is REPORTED as unrewritten below
+            // rather than silently rewritten or silently skipped.
+            const all = index.inboundFor(from)
+            const entries = all.filter(e => e.kind !== 'href')
+            const unrewritten = all.filter(e => e.kind === 'href')
             if (entries.length === 0) {
-                return { from, to, updated: [], failures: [] }
+                return { from, to, updated: [], failures: [], unrewritten }
             }
 
             const byEntity = new Map()
@@ -658,7 +721,7 @@ export function createRefs(db, prebuiltIndex = null) {
                 }
             }
 
-            return { from, to, updated, failures }
+            return { from, to, updated, failures, unrewritten }
         },
     }
 }

package/src/report.js

@@ -37,6 +37,46 @@ function reportWanted() {
     return !!(runtime.options?.json || runtime.options?.reportRequested)
 }
 
+// How many finished cycles to keep. Small on purpose: this is "what did my
+// last few edits do", not an audit log, and each entry holds one record per
+// entity rendered in that cycle.
+const HISTORY_LIMIT = 10
+
+function history() {
+    runtime.state ??= {}
+    runtime.state.reportHistory ??= []
+    return runtime.state.reportHistory
+}
+
+// The id the NEXT cycle will carry.
+//
+// A caller that writes a file needs to name the cycle its write will be
+// picked up by BEFORE that cycle exists — otherwise "did my edit land" is
+// unanswerable except by watching the clock. Writes go through the
+// watcher's debounce, so the cycle after the current one is the answer.
+export function nextCycleId() {
+    return (runtime.state?.cycle?.id ?? 0) + 1
+}
+
+export function currentCycle() {
+    return runtime.state?.cycle ?? null
+}
+
+// Finished cycles, newest first. `n` of them.
+export function cycleHistory(n = 1) {
+    return history().slice(-Math.max(1, n)).reverse()
+}
+
+// Resolves when a cycle with at least this id has finished. Used by a
+// caller that wants its write and the resulting report in one round trip
+// instead of polling.
+export function whenCycleCompletes(id) {
+    const done = history().find(c => c.id >= id)
+    if (done) return Promise.resolve(done)
+    runtime.state.cycleWaiters ??= []
+    return new Promise(resolve => runtime.state.cycleWaiters.push({ id, resolve }))
+}
+
 // Cleared at the start of every cycle, so the report always describes the
 // LAST one rather than everything since the process started.
 //
@@ -49,14 +89,42 @@ function reportWanted() {
 // across cycles by design — it is the retry marker's in-memory twin, and
 // the exit code depends on this cycle's count, which resetRenderErrors
 // handles at the same point.
+//
+// Reset and IDENTITY are the same event — a report that describes "the last
+// cycle" is only meaningful if something names which cycle that was, and a
+// caller waiting on its own write needs to compare against something.
 export function resetReport() {
     if (!runtime.state) return
+    const previous = runtime.state.cycle
+    if (previous && !previous.finishedAt) finishCycle()
+    runtime.state.cycle = { id: nextCycleId(), startedAt: Date.now(), finishedAt: null }
     runtime.state.report = { rendered: [], skipped: [], unchanged: [], errors: [], warnings: [], gated: 0 }
     runtime.state.renderErrors = []
 }
 
+// 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
+    runtime.state.cycle.finishedAt = Date.now()
+    const record = { ...runtime.state.cycle, ...buildReport() }
+    const kept = history()
+    kept.push(record)
+    while (kept.length > HISTORY_LIMIT) kept.shift()
+
+    const waiters = runtime.state.cycleWaiters ?? []
+    runtime.state.cycleWaiters = waiters.filter(w => {
+        if (record.id < w.id) return true
+        w.resolve(record)
+        return false
+    })
+}
+
 function store() {
+    // The first cycle never passes through resetReport — that fires on the
+    // watcher's trigger, and a cold build has no earlier cycle to reset from.
+    // Without this the build everyone looks at first reports cycleId: null.
     runtime.state ??= {}
+    runtime.state.cycle ??= { id: 1, startedAt: Date.now(), finishedAt: null }
     runtime.state.report ??= { rendered: [], skipped: [], unchanged: [], errors: [], warnings: [], gated: 0 }
     return runtime.state.report
 }
@@ -157,7 +225,13 @@ export function renderErrorCount() {
 
 export function buildReport() {
     const report = store()
+    const cycle = runtime.state?.cycle
     return {
+        // Which cycle this describes. Without it, two reports read the same
+        // and "is this my edit's cycle or the one before it" has no answer.
+        cycleId: cycle?.id ?? null,
+        startedAt: cycle?.startedAt ?? null,
+        finishedAt: cycle?.finishedAt ?? null,
         rendered: report.rendered,
         skipped: report.skipped,
         unchanged: report.unchanged,