mikser-io 9.76.0 → 9.78.0

package/README.md

@@ -315,7 +315,7 @@ Mikser itself has a previous chapter: the [legacy 7.x line](https://github.com/a
 | [Entities](./docs/entities.md)               | Users & Developers | Entity model, operations, journal, catalog         |
 | [Rendering](./docs/rendering.md)             | Users & Developers | Render pipeline, render plugins, render modes      |
 | [Watch Mode](./docs/watch-mode.md)           | Users              | File watching, scheduled tasks, incremental builds |
-| [Diagnostics](./docs/diagnostics.md)         | Users & Developers | **"Why did it do that?"** — `--explain`, `--json`, `--verify`, the sqlite tables, and every introspection surface, indexed by the question it answers |
+| [Diagnostics](./docs/diagnostics.md)         | Users & Developers | **"Why did it do that?"** — `--explain`, `--json`, `--audit-output`, the sqlite tables, and every introspection surface, indexed by the question it answers |
 | [MCP](https://github.com/almero-digital-marketing/mikser-io-mcp#readme) | Users              | The `mikser-io-mcp` plugin — tool surface, `mikser://` resources, twelve worked AI-driven scenarios |
 | [Caching](./docs/caching.md)                 | Users (production) | The `cache: true` disk cache + working nginx config for reverse-proxy failover |
 | [Architecture](./docs/architecture.md)       | Developers         | Module-level reference — what's in each file       |

package/app.js

@@ -35,14 +35,14 @@ function locate(argv) {
     // What to ask the instance for. Report-only commands go over the same
     // socket as a build: they read, so running them locally never damaged
     // anything, but a catalogue being written by another process is not a
-    // catalogue anyone can answer from — a --verify against a half-finished
+    // catalogue anyone can answer from — a --audit-output against a half-finished
     // cycle reports drift that is not there.
     const tool = value('--tool')
     const explain = value('--explain')
     const request = has('--tools') ? { type: 'report', tools: true, json: has('--json') }
         : tool                    ? { type: 'report', tool, toolArgs: value('--tool-args'), json: has('--json') }
         : explain                 ? { type: 'report', explain, json: has('--json') }
-        : has('--verify')         ? { type: 'report', verify: true, json: has('--json') }
+        : has('--audit-output')   ? { type: 'report', auditOutput: true, json: has('--json') }
         : { type: 'build', clear: has('--clear') }
 
     return {

package/docs/api-reference.md

@@ -41,7 +41,7 @@ await runtime.start()
 | `watch` | boolean | `false` | Watch mode |
 | `force` | boolean | `false` | Rebuild everything; disable incremental dispatch |
 | `resume` | boolean | `false` | Continue from journal left by a previous interrupted run; skip the initial filesystem scan |
-| `verify` | boolean | `false` | Verify output folder against manifest; report drift instead of building |
+| `auditOutput` | boolean | `false` | Audit the output folder against the snapshots the last build recorded — detects files changed or removed outside mikser, not a render that changed |
 | `debug` | boolean | `false` | Debug logging |
 | `trace` | boolean | `false` | Trace logging |
 | `threads` | number | `4` | Worker thread count |

package/docs/configuration.md

@@ -53,7 +53,7 @@ These options are part of `runtime.options` and apply to the engine itself.
 | `watch` | `-w, --watch` | boolean | `false` | Watch source folders for changes and rebuild incrementally. |
 | `force` | `-f, --force` | boolean | `false` | Rebuild everything; disable incremental dispatch. |
 | `resume` | `-R, --resume` | boolean | `false` | Continue from journal entries left by a previous interrupted run; skip the initial filesystem scan. The journal table survives crashes, so an interrupted cycle can be picked up by re-running with `--resume`. |
-| `verify` | `--verify` | boolean | `false` | Verify the output folder against the manifest snapshot — report drift instead of building. |
+| `verify` | `--audit-output` | boolean | `false` | Verify the output folder against the manifest snapshot — report drift instead of building. |
 | `debug` | `-d, --debug` | boolean | `false` | Enable debug-level logging. |
 | `trace` | `-t, --trace` | boolean | `false` | Enable trace-level logging (very verbose). |
 | `threads` | — | number | `4` | Worker thread count for the Piscina pools (`renderWorkers`, `postprocessWorkers`). Both pools are lazy (`minThreads: 0` + `idleTimeout: 30_000`) so INLINE-only workloads spin up zero workers. |

package/docs/diagnostics.md

@@ -14,12 +14,12 @@ engine source, the entry point is missing and belongs on this page.
 | --- | --- |
 | Why didn't this page rebuild? | [`--explain`](#--explain-entity) |
 | What did this build actually change? | [`--json`](#--json) |
-| Does the output folder match what mikser thinks it wrote? | [`--verify`](#--verify) |
+| Does the output folder match what mikser thinks it wrote? | [`--audit-output`](#--audit-output) |
 | What happened during the last cycle, in order? | [`mikser_journal`](#mikser_journal) |
 | 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) |
+| Two files seem to fight over one output | [`--explain`](#--explain-entity), [`--audit-output`](#--audit-output) |
 | Which source file produced this built output? | [`runtime.manifest`](#runtimemanifest), `mikser_which` |
 | Where was this VALUE written — file, field, line? | [`runtime.provenance`](#runtimeprovenance) |
 | What would break if I changed this file? | [`runtime.manifest`](#runtimemanifest) `affectedBy` |
@@ -203,8 +203,8 @@ make that readable — "broke just now" and "broken for an hour" are
 different situations. The marker clears itself on the first success.
 
 **A one-shot build with render errors exits `1`.** That is the signal a CI
-gate needs, because `mikser && mikser --verify` would otherwise pass a
-build in which nothing rendered: `--verify` compares the output against the
+gate needs, because `mikser && mikser --audit-output` would otherwise pass a
+build in which nothing rendered: `--audit-output` compares the output against the
 manifest, both of which still describe the last good render. Watch mode
 keeps running — a failed render there is a state to fix on the next cycle,
 not a reason to tear down the watcher.
@@ -274,7 +274,7 @@ Warnings carry a stable `code` alongside their prose, so a test can
 assert "this build produced no preset-no-match" without grepping a
 sentence someone may later reword.
 
-### `--verify`
+### `--audit-output`
 
 Walks the output folder against the recorded snapshots and reports drift
 instead of building. Four categories, and the split matters:
@@ -299,7 +299,7 @@ missing or mismatched, `1` if only warnings, `0` when clean, and `2` when
 there is no manifest to check against.
 
 ```bash
-npx mikser --verify || echo "output folder has drifted"
+npx mikser --audit-output || echo "output folder has drifted"
 ```
 
 A destination is resolved against the output folder first and, when that
@@ -313,6 +313,25 @@ it. That is normal for anything written without a render snapshot (the
 `files` and `data` plugins), and a real signal for a page whose layout
 stopped producing it.
 
+**What a pass means, and what it does not.** It compares each output file
+against the hash *its own render recorded*. Every render rewrites that
+snapshot, so a render whose output changed records the new bytes and then
+matches them. It is a tampering check — files edited, truncated or removed
+outside mikser — and it cannot, by construction, tell you a render changed.
+
+That question is answered by **`output-drift`** instead, reported by the build
+itself rather than by a check afterwards: at the moment a snapshot is
+replaced, the row being overwritten is still readable, so an output that moved
+while its `inputHash` stood still is knowable exactly once — before the
+evidence is gone. Unchanged inputs and changed bytes means the cause was not
+the content: an upgraded renderer, a changed helper, a dependency that shifted
+under the build.
+
+Only entities that actually rendered can drift, so an ordinary build reports
+on what moved. Under `--force` everything re-renders with unchanged inputs,
+which makes it a full sweep — **`mikser --force` after a package upgrade is
+the regression check**.
+
 ### The rest, briefly
 
 | Flag | Use |
@@ -344,16 +363,16 @@ npx mikser --tools
 npx mikser --tool which --tool-args '{"destination":"/bg/index.html","text":"Контакти"}'
 ```
 
-Tool names are **bare** here — `explain`, `verify`, `sources`, `which`. The
+Tool names are **bare** here — `explain`, `audit_output`, `sources`, `which`. The
 `mikser_` prefix belongs to MCP, where tool names share one flat namespace
-across every server a client has connected to and an unprefixed `verify`
+across every server a client has connected to and an unprefixed `audit_output`
 would collide with anyone else's. The engine has no such problem, and
 `mikser --tool mikser_explain` says mikser twice. The prefix is added at
 the session boundary, so an MCP client sees exactly the names it always
 did. Either form is accepted on the CLI, because an agent reading MCP
 documentation should not have to know which surface stripped what.
 
-A report-and-exit run — `--explain`, `--verify`, `--tools`, `--tool` —
+A report-and-exit run — `--explain`, `--audit-output`, `--tools`, `--tool` —
 never wipes the cache, even when the config or the schema version has
 moved. Wiping for one destroys the state it was asked to describe and
 then answers from the empty result as though that were the answer;
@@ -396,7 +415,7 @@ language, which the engine has no business owning. A tool needing real
 validation registers through `runtime.options.mcp` with zod, which is
 what every tool in that plugin does.
 
-**`explain`, `verify`, `sources` and `build_report` are the engine's own**,
+**`explain`, `audit_output`, `sources` and `build_report` are the engine's own**,
 registered in `src/builtin-tools.js` rather than by a plugin. `sources`
 is the reverse lookup — what produced this destination, each source
 tagged with how it got there — reading the `refClosure` through
@@ -404,16 +423,16 @@ tagged with how it got there — reading the `refClosure` through
 `mikser-io-mcp`'s `which`, which reports each occurrence's line and
 whether the string begins it: a declaration usually does and a use
 usually does not, which separates the two in any text format without a
-per-language grammar. That is what makes `--tool mikser_verify` work on a bare engine,
-the same as `--verify` — before, the engine's diagnostics needed an agent
+per-language grammar. That is what makes `--tool mikser_audit_output` work on a bare engine,
+the same as `--audit-output` — before, the engine's diagnostics needed an agent
 surface configured to be reachable as tools, which is backwards.
 
-`--explain` and `--verify` stay as flags rather than becoming `--tool`
+`--explain` and `--audit-output` stay as flags rather than becoming `--tool`
 invocations. They are not a second implementation: the flag and the tool
-both call `explain()` and `manifest.verify()`. Routing the flag through
+both call `explain()` and `manifest.auditOutput()`. Routing the flag through
 the tool would add a JSON serialize-and-reparse for nothing. What the
 flags carry that the tool cannot is presentation and exit status —
-`formatExplain`'s aligned columns are for a person, and `--verify` exits
+`formatExplain`'s aligned columns are for a person, and `--audit-output` exits
 `0` / `1` / `2` for OK / WARN / FAIL, a CI gate contract that `--tool`'s
 `0` / `1` cannot express without lying about one of the three.
 
@@ -423,7 +442,7 @@ Everything above assumes a shell on the machine. Three of these questions
 are also answerable from a running server, which is what CI, a dashboard,
 an SDK, or an agent speaking MCP actually has.
 
-**MCP** — `mikser_explain`, `mikser_build_report`, `mikser_verify`,
+**MCP** — `mikser_explain`, `mikser_build_report`, `mikser_audit_output`,
 alongside the existing `mikser_refs_*`, `mikser_layouts_inspect` and the
 `mikser://logs/recent` resource. Four more answer the questions a shell
 would otherwise be needed for: `mikser_search` finds a string across
@@ -613,7 +632,7 @@ What was rendered and whether it needs redoing.
 | `sourcesBehind(snapshot)` | the source entities that fed one render, each with `via` naming HOW it got there (layout, partial, ref, or the recorded query it matched) |
 | `sourcesOf(destination)` | the same across every entity claiming a destination, unioned — what `mikser_which` answers from |
 | `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 |
+| `verify({outputFolder})` | `{ verdict, missing, mismatched, unverifiable, orphaned, collisions }` — what `--audit-output` 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 |
@@ -764,10 +783,10 @@ There is no opt-out. A flag for running a second engine on a held folder
 only ever enabled the accident this surface prevents, and stopping the
 instance serves every case it was reached for.
 
-`--tool`, `--tools`, `--verify` and `--explain` forward as well, and for a
+`--tool`, `--tools`, `--audit-output` and `--explain` forward as well, and for a
 different reason than builds do. They only read, so running one locally never
 damaged anything — it just could not be trusted: on a large site a local
-`--verify` reads a catalogue the instance is halfway through writing and
+`--audit-output` reads a catalogue the instance is halfway through writing and
 reports drift that is a cycle in progress. The instance has the settled state
 and the config that produced it. Exit codes cross the socket unchanged, so
 `--explain` still answers 3 for an entity that is not there.

package/docs/getting-started.md

@@ -112,7 +112,7 @@ mikser [options]
   -f, --force                      Rebuild everything; disable incremental dispatch
   -R, --resume                     Continue from journal entries left by a previous
                                    interrupted run; skip the initial filesystem scan
-      --verify                     Verify output folder against manifest; report
+      --audit-output                     Audit output against recorded snapshots; report
                                    drift instead of building
   -d, --debug                      Show debug log statements
   -t, --trace                      Show trace log statements

package/package.json

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

package/src/builtin-tools.js

@@ -1,10 +1,10 @@
 // The engine's own diagnostics, registered as tools.
 //
-// `explain()`, `manifest.verify()` and `buildReport()` are engine functions,
+// `explain()`, `manifest.auditOutput()` and `buildReport()` are engine functions,
 // but the tools wrapping them were registered by the mcp plugin — so
 // `--tool mikser_explain` needed an agent surface configured while `--explain`
 // did not. That is backwards for the engine's own diagnostics, and it is why
-// `--verify` and `--explain` could not simply become `--tool` invocations.
+// `--audit-output` and `--explain` could not simply become `--tool` invocations.
 //
 // Registering them here fixes the direction: they exist on a bare engine, the
 // CLI flags become renderings of them rather than parallel implementations,
@@ -12,7 +12,7 @@
 //
 // Names are BARE — `explain`, not `mikser_explain`. The prefix exists because
 // MCP tool names share one flat namespace across every server a client has
-// connected to, so an unprefixed `verify` would collide with any other server
+// connected to, so an unprefixed `audit_output` would collide with any other server
 // offering one. That is the protocol's constraint, not the engine's: on the CLI
 // `mikser --tool mikser_explain` says mikser twice. So the registry holds the
 // bare name and `mikser-io-mcp` adds the prefix when it binds a tool into a
@@ -70,7 +70,7 @@ export function registerBuiltinTools() {
     )
 
     registerTool(
-        'verify',
+        'audit_output',
         {
             description:
                 'Check the output folder against what the manifest recorded: files missing, files whose bytes no '
@@ -81,14 +81,14 @@ export function registerBuiltinTools() {
         },
         async () => {
             try {
-                if (!runtime.manifest?.verify) return fail('No manifest available — nothing to verify against')
+                if (!runtime.manifest?.auditOutput) return fail('No manifest available — nothing to audit against')
                 // The verdict comes FROM the manifest, which is the single
                 // place that rule lives. Three consumers deriving it from
                 // counts is how one of them silently stopped counting
                 // collisions.
                 return ok({
                     snapshots: runtime.manifest.size?.() ?? null,
-                    ...(await runtime.manifest.verify()),
+                    ...(await runtime.manifest.auditOutput()),
                 })
             } catch (err) {
                 return fail(err.message)

package/src/catalog.js

@@ -356,7 +356,7 @@ onFinalize(async () => {
     await applyJournalMutations()
 
     // Checkpoint the WAL so the main file size stays representative
-    // and external tools (mikser --verify on a separate run, debug
+    // and external tools (mikser --audit-output on a separate run, debug
     // scripts) see committed state. PASSIVE never blocks readers or
     // writers; it only catches up what it can.
     if (!db?.isOpen) return

package/src/engine.js

@@ -231,7 +231,7 @@ export async function runReportOnly(request = {}) {
         toolArgs = runtime.options.toolArgs,
         json = runtime.options.json,
         explain = runtime.options.explain,
-        verify = runtime.options.verify,
+        auditOutput = runtime.options.auditOutput,
     } = request
 
     if (tools) {
@@ -292,7 +292,7 @@ export async function runReportOnly(request = {}) {
     if (explain) {
         // Exit codes:
         //   0 — the entity was found and described
-        //   3 — not in the catalog (distinct from --verify's 1/2, which are
+        //   3 — not in the catalog (distinct from --audit-output's 1/2, which are
         //       about output drift; "no such entity" is neither clean nor
         //       corrupt, it is a question that could not be answered)
         const { explain: explainEntity, formatExplain } = await import('./explain.js')
@@ -301,13 +301,13 @@ export async function runReportOnly(request = {}) {
         return report.found ? 0 : 3
     }
 
-    if (verify) {
+    if (auditOutput) {
         if (!runtime.manifest) {
             logger.error('Verify: no manifest available — nothing to check against')
             return 2
         }
         const { verdict, missing, mismatched, unverifiable, orphaned, collisions } =
-            await runtime.manifest.verify()
+            await runtime.manifest.auditOutput()
         const total = runtime.manifest.size()
 
         for (const e of missing)      logger.error('Missing:    %s (entity %s)', e.destination, e.id)
@@ -325,8 +325,28 @@ export async function runReportOnly(request = {}) {
         // reads as success at a glance even though the exit code is right.
         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, %d collisions',
+            'Audit %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)
+
+        // Say what a pass means, because the name promises more than the check
+        // can deliver.
+        //
+        // This compares each output file against the hash its OWN render
+        // recorded. Every render rewrites that snapshot, so a render whose
+        // output changed records the new bytes and then matches them: a
+        // rendering regression verifies clean, by construction, and no amount
+        // of care in the comparison changes that. It is a tampering check —
+        // files edited, truncated or removed outside mikser — not a
+        // regression check.
+        //
+        // Said on a PASS only. On a failure the listed differences are the
+        // message, and this would bury them.
+        if (verdict === 'OK') {
+            logger.info(
+                'Audit compares each output against the hash its own render recorded, so it catches files '
+                + 'changed or removed outside mikser — not a render that changed. A render that changed is '
+                + 'reported as it happens, under `output-drift`.')
+        }
         return verdict === 'FAIL' ? 2 : verdict === 'WARN' ? 1 : 0
     }
 
@@ -373,8 +393,8 @@ export async function setup(options) {
     }
     runtime.state = {}
     // The engine's own diagnostics, as tools. Registered here rather than by a
-    // plugin so they exist on a bare engine — `--tool mikser_verify` must not
-    // need an agent surface configured when `--verify` does not.
+    // plugin so they exist on a bare engine — `--tool mikser_audit_output` must not
+    // need an agent surface configured when `--audit-output` does not.
     registerBuiltinTools()
 
     // One engine per working folder: publish the control socket when this
@@ -392,7 +412,7 @@ export async function setup(options) {
             .option('-w --watch', 'watch entities for changes', false)
             .option('-f --force', 'rebuild everything; disable incremental dispatch', false)
             .option('-R --resume', 'continue from journal entries left by a previous interrupted run; skip the initial filesystem scan', false)
-            .option('--verify', 'verify output folder against manifest; report drift instead of building', false)
+            .option('--audit-output', 'audit the output folder against the snapshots the last build recorded — detects files changed or removed outside mikser, NOT a render that changed', false)
             .option('--explain <entity>', 'explain one entity — layout, destination, hashes, refClosure, and whether a build would re-render it. Accepts an id, a meta.href, or an id without its extension. Reports instead of building.')
             .option('--json', 'machine-readable output (with --explain, --tool, and for a build\'s render/skip/warning report)', false)
             .option('--tools', 'list the tools this build exposes, then exit', false)
@@ -541,7 +561,7 @@ export async function setup(options) {
         // Listing from there returned exactly one, the tool the mcp substrate
         // creates for itself. By `import` every onLoaded has run and the
         // registry is complete. Nothing is imported, because this exits first,
-        // the same way --explain and --verify do.
+        // the same way --explain and --audit-output do.
         if (runtime.options.tools || runtime.options.tool) {
             const code = await runReportOnly()
             if (code !== null) process.exit(code)
@@ -552,7 +572,7 @@ export async function setup(options) {
         const logger = useLogger()
         logger.debug(runtime.options, 'Mikser options')
 
-        // --verify is a standalone read-only mode. Manifest has already
+        // --audit-output is a standalone read-only mode. Manifest has already
         // loaded in its own onLoaded (registered earlier at module
         // import). We diff disk against snapshots, print the report,
         // and exit. No build phases run.
@@ -563,16 +583,16 @@ export async function setup(options) {
         //                 corruption, but state is messy)
         //   2 — errors   (missing or mismatched files — output is
         //                 actually wrong on disk)
-        // --explain: report on one entity and exit, like --verify. Placed
+        // --explain: report on one entity and exit, like --audit-output. Placed
         // before it because a caller reaching for both means the explain.
         //
         // Exit codes:
         //   0 — the entity was found and described
-        //   3 — not in the catalog (distinct from --verify's 1/2, which are
+        //   3 — not in the catalog (distinct from --audit-output's 1/2, which are
         //       about output drift; "no such entity" is neither clean nor
         //       corrupt, it is a question that could not be answered)
         // The same three commands the instance answers over the socket —
-        // one implementation, so a forwarded --verify cannot disagree with a
+        // one implementation, so a forwarded --audit-output cannot disagree with a
         // local one about what it checked.
         const code = await runReportOnly()
         if (code !== null) process.exit(code)
@@ -969,13 +989,13 @@ export async function setup(options) {
 
         // 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
+        // Reported per cycle rather than only by --audit-output 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
+        // re-warn on every unrelated build; --audit-output is where the standing
         // state lives.
         for (const [destination, ids] of renderedTo) {
             if (ids.size < 2) continue
@@ -1249,7 +1269,7 @@ export async function setup(options) {
         // document is the only thing on it and can be piped to jq.
         emitReport()
 
-        // Non-zero for a one-shot build, so `mikser && mikser --verify` cannot
+        // Non-zero for a one-shot build, so `mikser && mikser --audit-output` cannot
         // pass with every page in the site stale. `exitCode` rather than
         // process.exit so the report above is flushed and shutdown runs.
         //
@@ -1259,7 +1279,7 @@ export async function setup(options) {
         // past between two green builds — so the exit code is precisely the
         // signal CI needs and the one interactive use must not have.
         //
-        // 1, not 2: --verify already uses 2 for output drift and --explain 3
+        // 1, not 2: --audit-output already uses 2 for output drift and --explain 3
         // for not-found. "The build ran and some renders threw" is its own
         // thing.
         if (failed && !runtime.options.watch) process.exitCode = 1

package/src/explain.js

@@ -7,7 +7,7 @@
 // read plugin source and hand-query runtime/mikser.sqlite — which works, and
 // needs knowledge a user of the tool should not need.
 //
-// Follows --verify's shape: report and exit, no build phases run.
+// Follows --audit-output's shape: report and exit, no build phases run.
 import { inputHashOf, inputPartsOf, diffInputParts, lookupKeys, checksum as fileChecksum } from './utils.js'
 import { filterKey } from './track.js'
 import { findEntity, findEntities, findById } from './catalog.js'

package/src/instance.js

@@ -70,7 +70,7 @@ export function socketPath(workingFolder) {
 // ship together, so there is nothing to negotiate and no version to carry.
 //
 //   → { type: 'build',  config, clear }
-//   → { type: 'report', config, tool, tools, toolArgs, explain, verify, json }
+//   → { type: 'report', config, tool, tools, toolArgs, explain, auditOutput, json }
 //   ← { type: 'log', chunk }        (zero or more, in order)
 //   ← { type: 'done', code }
 //   ← { type: 'refused', reason, detail }
@@ -255,7 +255,7 @@ async function configStale() {
 // Report-only commands, answered from the live catalogue.
 //
 // These read; they do not write, so running them locally was safe for the
-// FILES. It was not safe for the ANSWER. A local --verify at ten thousand
+// FILES. It was not safe for the ANSWER. A local --audit-output at ten thousand
 // pages reads a catalogue the instance is in the middle of writing and reports
 // drift that is a half-finished cycle, and a local --tool answers from
 // whatever the last build left rather than from what is true now.

package/src/manifest.js

@@ -7,7 +7,7 @@
 //     own bytes are identical to last cycle AND none of its tracked
 //     dependencies (layout, partials, $-refs, queries) mutated, the
 //     render is short-circuited
-//   - `mikser --verify` walks output folder against recorded snapshots
+//   - `mikser --audit-output` walks output folder against recorded snapshots
 //
 // Storage: `mikser_snapshots` table in the engine's sqlite database,
 // alongside `mikser_entities` and `mikser_refs`. Composite primary key
@@ -106,7 +106,7 @@ registerSchema('mikser_snapshots', SNAPSHOTS_SCHEMA)
 // consequences all follow from that one absence: the entity is gated at
 // import next cycle (its own source did not change), so it is never
 // re-dispatched; the manifest still describes the last good render, so
-// --verify is clean; and --explain reports `[current]` and `would be
+// --audit-output is clean; and --explain reports `[current]` and `would be
 // SKIPPED` for a page whose render is throwing — the one tool whose job is
 // "why is this not rebuilding", answering "because there is nothing to do".
 //
@@ -1063,8 +1063,8 @@ export function createManifest(db) {
 
         // Walk the output folder against recorded snapshots, returning
         // a diff describing missing / mismatched / orphaned /
-        // unverifiable. Backs `mikser --verify`. Pure: no mutations.
-        async verify({ outputFolder } = {}) {
+        // unverifiable. Backs `mikser --audit-output`. Pure: no mutations.
+        async auditOutput({ outputFolder } = {}) {
             outputFolder = outputFolder || runtime.options.outputFolder
             const missing = []
             const mismatched = []
@@ -1160,6 +1160,7 @@ export function createManifest(db) {
         _stmtSelectByDestination: stmtSelectByDestination,
         _stmtDeleteByDestination: stmtDeleteByDestination,
         _stmtDeleteByPK:         stmtDeleteByPK,
+        _stmtLookup:             stmtLookup,
         _stmtUpsert:             stmtUpsert,
     }
     return manifest
@@ -1284,7 +1285,7 @@ onFinalize(async () => {
     // `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.
+    // re-rendered it, and --audit-output 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
@@ -1304,7 +1305,7 @@ onFinalize(async () => {
     // yet, and the file goes — with `Rendered: 1`, a green build and no
     // warning. A second build does not fix it (nothing changed), nor does
     // touch (the input hash is the same); only a real content edit re-renders
-    // it. Only --verify ever said so, and renaming an extension is the most
+    // it. Only --audit-output ever said so, and renaming an extension is the most
     // common action there is during a migration.
     const claimedByThisCycle = new Set()
     for (const { entity } of renderedEntries) {
@@ -1366,6 +1367,9 @@ onFinalize(async () => {
     // `parent` is checked too, mirroring _stmtDeleteByIdOrParent — a deleted
     // parent takes its paginated children's snapshots with it.
     const recordedSnapshots = []
+    // Entities whose output moved while their inputs did not — collected
+    // inside the transaction, reported by the caller once it commits.
+    const drifted = []
     for (const { entity, deps, metaReads, consumedReads } of renderedEntries) {
         if (deleted.has(entity.id) || (entity.parent && deleted.has(entity.parent))) continue
         const outputHash = await hashOutputFile(entity.destination)
@@ -1383,8 +1387,59 @@ onFinalize(async () => {
             m._stmtDeleteByPK.run(id, destination)
         }
         // 3c. Record successful renders.
+        //
+        // Drift: the same inputs produced different output.
+        //
+        // The row about to be replaced is still readable here, and it carries
+        // both hashes — so an output that moved while its inputHash stood
+        // still is knowable at the moment it happens, for the cost of one
+        // lookup. That is a rendering change nobody asked for: an upgraded
+        // renderer, a changed helper, a dependency that shifted under the
+        // build. Every entity input is in inputHash by construction, so if
+        // that did not move, the cause was not the content.
+        //
+        // Recorded here rather than checked later because later is too late —
+        // the render rewrites its own snapshot, so by the time anything asks,
+        // the evidence has been replaced by the new bytes agreeing with
+        // themselves. That is why --audit-output reported OK on a regression.
+        //
+        // Only entities that actually rendered can drift. Under an ordinary
+        // build the unchanged ones are skipped and never reach here, so this
+        // reports on what moved; under --force everything re-renders with
+        // unchanged inputs, which makes it a full sweep.
         for (const snap of recordedSnapshots) {
+            const prior = m._stmtLookup.get(snap.id, snap.destination)
+            if (prior
+                && prior.inputHash
+                && prior.inputHash === snap.inputHash
+                && prior.outputHash
+                && snap.outputHash
+                && prior.outputHash !== snap.outputHash) {
+                drifted.push({ id: snap.id, destination: snap.destination })
+            }
             m._stmtUpsert.run(snapToRow(snap))
         }
     })
+
+    // Reported after the transaction, so the log never describes a commit
+    // that did not happen.
+    //
+    // A warning, not an error: identical inputs CAN legitimately produce
+    // different bytes — a template that prints a timestamp, an id drawn at
+    // random. Those are worth knowing about once, and then worth fixing,
+    // because a render that is not a function of its inputs cannot be
+    // cached, compared or trusted to be reproducible.
+    if (drifted.length) {
+        const SHOWN = 10
+        for (const { id, destination } of drifted.slice(0, SHOWN)) {
+            logger.warn({ code: 'output-drift', entity: id, destination },
+                'Output changed with unchanged inputs: %s → %s', id, destination)
+        }
+        logger.warn({ code: 'output-drift-summary', drifted: drifted.length },
+            '%d render(s) produced different bytes from the same inputs%s. Nothing about the content '
+            + 'moved, so the cause is outside it — an upgraded renderer, a changed helper, a dependency '
+            + 'that shifted under the build. This is the check --audit-output structurally cannot make: '
+            + 'a render rewrites its own snapshot, so afterwards the new bytes agree with themselves.',
+            drifted.length, drifted.length > SHOWN ? `, ${SHOWN} shown` : '')
+    }
 })

package/src/plugins/api.js

@@ -964,10 +964,10 @@ export function api(options = {}) {
 
             // ── Diagnostics ────────────────────────────────────────
             //
-            // The three questions --explain, --json and --verify answer, for
+            // The three questions --explain, --json and --audit-output answer, for
             // a RUNNING server: CI asking "did that deploy actually rebuild
             // anything", a dashboard, an SDK, anything not speaking MCP.
-            // `mikser && mikser --verify` becomes a request against the
+            // `mikser && mikser --audit-output` becomes a request against the
             // instance that is actually serving.
             //
             // Gated on their own `diagnostics` operation, which is in NEITHER
@@ -1006,9 +1006,9 @@ export function api(options = {}) {
                 }
             })
 
-            router.get('/verify', auth, allow('diagnostics'), async (req, res) => {
+            router.get('/audit-output', auth, allow('diagnostics'), async (req, res) => {
                 try {
-                    if (!runtime.manifest?.verify) {
+                    if (!runtime.manifest?.auditOutput) {
                         return res.status(503).json({ error: 'No manifest available — nothing to verify against' })
                     }
                     // 200 either way — the check ran and this is its answer. A
@@ -1017,7 +1017,7 @@ export function api(options = {}) {
                     // 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()
+                    const diff = await runtime.manifest.auditOutput()
                     return res.json({ snapshots: runtime.manifest.size?.() ?? null, ...diff })
                 } catch (err) {
                     logger.error('Api verify error: %s', err.message)

package/src/references.js

@@ -6,7 +6,7 @@
 // never asks whether that file exists. A wrong preset name, a wrong extension,
 // or a source whose derivative silently failed to render all produce a
 // well-formed url pointing at nothing, and every existing surface stays green:
-// nothing threw, --verify compares snapshots against what was rendered rather
+// nothing threw, --audit-output compares snapshots against what was rendered rather
 // than against what those renders point at, and mikser_refs_broken tracks
 // document-to-document refs, not urls.
 //

package/src/report.js

@@ -80,7 +80,7 @@ export function whenCycleCompletes(id) {
     // and cannot tell whether the work happened.
     if (isReportOnlyRun()) {
         return Promise.reject(new Error(
-            'No build runs in a --tool/--explain/--verify invocation, so there is no cycle to wait '
+            'No build runs in a --tool/--explain/--audit-output invocation, so there is no cycle to wait '
             + 'for. The write itself has landed. Run `mikser` to build it, or use --server with the '
             + 'MCP endpoint, where a watch cycle exists to await.'))
     }

package/src/tools.js

@@ -82,7 +82,7 @@ export function toolSchemas() {
 export async function invokeTool(name, args = {}) {
     // Names in this registry are BARE. The `mikser_` prefix belongs to MCP,
     // where tool names share one flat namespace across every connected server
-    // and an unprefixed `verify` would collide with anyone else's — a
+    // and an unprefixed `audit_output` would collide with anyone else's — a
     // constraint of that protocol, not of the engine. `mikser --tool
     // mikser_explain` says mikser twice.
     //
@@ -129,5 +129,5 @@ export function toolResultFailed(result) {
 // settle and Node drained the loop and left.
 export function isReportOnlyRun() {
     const options = runtime.options ?? {}
-    return Boolean(options.explain || options.verify || options.tool || options.tools)
+    return Boolean(options.explain || options.auditOutput || options.tool || options.tools)
 }