mikser-io 9.30.0 → 9.37.1

package/CLAUDE.md

@@ -198,6 +198,32 @@ brevity.
   Strings produce a v9 migration error pointing at the new shape.
 - `manager.js` — file watching (chokidar) and cron scheduling.
 - `source.js` — `useSource` codifies the folder-of-files pattern.
+- `tools.js` — tool registry. `registerTool(name, {description,
+  inputSchema}, handler)` / `toolNames()` / `toolSchema()` / `invokeTool()`,
+  stored on `runtime.tools`. There are TWO agent workflows — one speaking
+  MCP over HTTP, one running the CLI and reading its output — and every
+  tool used to live in the mcp plugin, reachable only through a session,
+  so the CLI agent saw a much smaller engine. The registry is substrate
+  and the transports are consumers: `--tools` / `--tool` dispatch through
+  it, mcp mirrors its registrations into it, and a tool registered by any
+  plugin reaches both surfaces with no per-tool CLI code. MCP keeps the
+  tools themselves, the transport, sessions, resources and prompts.
+  Dispatched at `onImport`, not `onLoaded` — the engine's own onLoaded is
+  registered during setup(), ahead of the plugins that register the tools.
+- `builtin-tools.js` — the engine's own diagnostics as tools
+  (`mikser_explain`, `mikser_verify`, `mikser_build_report`). Registered
+  by the engine, not by mcp, so `--tool mikser_verify` works on a bare
+  engine exactly as `--verify` does. Schemas use a neutral
+  `{ type, required?, description? }` vocabulary; mcp converts to zod at
+  bind time, because the registry must not depend on one transport's
+  schema library.
+- `provenance.js` — where a value was WRITTEN: source, field path, line,
+  column. Formats register (`registerProvenanceFormat` / `probeFormat`)
+  rather than being special-cased; yaml/json/front-matter use the `yaml`
+  parser's ranges, and anything without ranges uses the one-pass uuid
+  probe. Field paths are free; line/col is computed on demand and cached
+  in `mikser_provenance` against the entity's checksum, so a build pays
+  nothing.
 - `routes.js` — HTTP route registry. Plugins mount on
   `runtime.options.app` directly; the Express router stack has the
   paths but not the intent (loopback-only? streaming?). So plugins
@@ -353,7 +379,15 @@ Test coverage: `test/unit/source-sweep.test.js`.
   camelCase: `import { vector } from 'mikser-io-vector'`,
   `import { renderHbs } from 'mikser-io'`. Consumer uses
   `plugins: [vector({...})]` — never the bare string.
-- **MCP tools**: `mikser_<verb>` or `mikser_<subsystem>_<verb>`:
+- **Tool names**: the registry (`src/tools.js`) holds BARE names —
+  `explain`, `verify`, `sources`, `search`. The `mikser_` prefix is MCP's
+  namespacing, because its tool names are flat across every connected
+  server; `mikser-io-mcp` strips it when mirroring a registration into the
+  engine and re-adds it when binding into a session. `invokeTool` accepts
+  either form. On the CLI the prefix is stutter: `mikser --tool
+  mikser_explain` says mikser twice.
+- **MCP tools** (as a client sees them): `mikser_<verb>` or
+  `mikser_<subsystem>_<verb>`:
   `mikser_query_entities`, `mikser_read_entity`, `mikser_update_entity`,
   `mikser_delete_entity`, `mikser_render`, `mikser_refs_inbound`,
   `mikser_refs_outbound`, `mikser_refs_broken`, `mikser_refs_rename`,

package/docs/diagnostics.md

@@ -21,7 +21,9 @@ engine source, the entry point is missing and belongs on this page.
 | 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` |
+| Where was this VALUE written — file, field, line? | [`runtime.provenance`](#runtimeprovenance) |
 | What would break if I changed this file? | [`runtime.manifest`](#runtimemanifest) `affectedBy` |
+| I am an agent reading CLI output, not speaking MCP | [`--tools` / `--tool`](#the-two-agent-workflows) |
 | Did my schema validate anything at all? | [`schemas.names()`](#schemasnames--schemaslookup) |
 
 ## Command line
@@ -285,12 +287,102 @@ stopped producing it.
 | `-R, --resume` | continue from a previous interrupted run's journal; skips the filesystem scan |
 | `-r, --clear` | clear state before running |
 | `-d, --debug` / `-t, --trace` | raise log level; `trace` includes per-entity catalog writes |
+| `--tools` | list the registered tools, then exit; `--json` for full schemas |
+| `--tool <name>` | run one tool and print its result, then exit. `--tool-args '<json>'` supplies arguments |
 
 `--force` composes with the unchanged-output check: it redoes the work
 without touching files whose bytes did not move, so it is cheap to reach
 for and its `unchanged` count tells you how much of the catalog was stale
 by suspicion rather than in fact.
 
+## The two agent workflows
+
+There are two ways an agent drives mikser and they are equally real: one
+speaks MCP over HTTP, the other runs the CLI and reads its output. Both
+read the same tool registry, so neither sees a smaller engine than the
+other.
+
+```bash
+npx mikser --tools
+```
+
+```bash
+npx mikser --tool which --tool-args '{"destination":"/bg/index.html","text":"Контакти"}'
+```
+
+Tool names are **bare** here — `explain`, `verify`, `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`
+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` —
+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;
+measured, one `--tool mikser_query_entities` after an edit to
+`mikser.config.js` dropped 521 entities and replied `total: 0`. The
+staleness is still reported, loudly. A build still wipes, because a build
+is what repopulates.
+
+An empty catalog is said out loud too, before the answer: every tool
+replies `null` / `total: 0` / "no render claims this destination" when
+nothing has been built, and all of those read as "the thing you asked
+about does not exist".
+
+`--tools` lists what is registered, with `--json` for the full schemas.
+`--tool` runs one and prints its result; stdout carries only that result
+— the banner and every log line move to stderr, as under `--json` — so
+piping into `jq` works. Exit status is `0` on success, `1` when the tool
+itself reported an error, and `3` when the tool does not exist or its
+arguments are not valid JSON, because an agent reading CLI output has
+only the status to branch on.
+
+The registry lives in the engine (`registerTool` / `toolNames` /
+`invokeTool`), and the transports are consumers of it. That is what makes
+the parity hold rather than decay: a tool registered through
+`runtime.options.mcp` — by mcp, layouts, vector, or one written next week
+— is reachable from both surfaces the moment it exists, with no per-tool
+CLI code and no second list to keep in step. The mcp plugin still owns
+the tools themselves, the transport, sessions, resources and prompts; the
+engine knows only a name, a description, an input schema and a function.
+
+The mirroring runs both ways. mcp's registrations flow into the engine's
+registry, so everything it registers is reachable from `--tool`; and a
+session binds the engine's own registrations too, converting their schema
+to zod at bind time. The engine declares an input as
+`{ name: { type, required?, description? } }` rather than as zod, because
+the registry is transport agnostic and should not depend on one
+transport's schema library. The vocabulary covers string / number /
+boolean / array and stops there — anything richer would be a schema
+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**,
+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
+`manifest.sourcesOf`. Locating a string *inside* those sources stays in
+`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
+surface configured to be reachable as tools, which is backwards.
+
+`--explain` and `--verify` 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
+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
+`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.
+
 ## Over a transport
 
 Everything above assumes a shell on the machine. Three of these questions
@@ -306,7 +398,10 @@ 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
+source that produced it — reading recorded provenance where it exists and
+labelling each answer `meta-field` / `source-content` (recorded) or `scan`
+(not), because a recorded answer and a guessed one warrant different trust;
+and
 `mikser_update_entity({ dryRun: true })` reports the blast radius of an
 edit before making it.
 
@@ -438,6 +533,8 @@ What was rendered and whether it needs redoing.
 | `recordedHashes()` | the dep-hashes dependents last saw |
 | `queryAffected(mutated)` | which query-dependent snapshots this mutation hits |
 | `snapshotsAt(destination)` | every snapshot claiming a destination — the reverse of `snapshotsFor`, and the way back from a built file to what produced it |
+| `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 |
 | `collisions()` | destinations claimed by more than one entity, with the ids claiming each |
@@ -449,6 +546,15 @@ 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.
 
+`sourcesBehind` is the reverse of everything else here, and it lives in the
+engine because the `refClosure` IS the engine's record of what a render
+consumed — which is what makes the answer authoritative rather than a
+guess at which file might hold something. A bundle assembled from
+`findEntities({ collection: 'styles' })` records that query, so re-running
+it returns exactly the parts that went in. A query whose filter could not
+be serialized names no members: it invalidates on any mutation, which is
+not the same as "every entity fed this render".
+
 `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
@@ -457,6 +563,57 @@ 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.
 
+### `runtime.provenance`
+
+Where a value was **written** — source file, field path, line and column.
+
+| Method | Answers |
+| --- | --- |
+| `positionsFor(entity)` | `{ 'items[2].label': { line, col }, … }` for every leaf of the entity's meta |
+| `locate(entity, fieldPath)` | one position, or null |
+| `forget(id)` | drop a cached entry |
+
+The field PATH costs nothing — it comes from walking `entity.meta`, which is
+already in memory, so it is always available. Line and column need one parse
+of the raw source, and that happens **on demand**, never during a build. The
+result is cached in `mikser_provenance` against the entity's checksum, so the
+first question about a file pays one parse and every later one pays nothing
+until the file changes. A build pays nothing at all.
+
+Formats are handled by registered handlers rather than by a chain of
+`if (extension === …)`:
+
+| Format | How the position is found |
+| --- | --- |
+| yaml, json | `YAML.parseDocument` reports a range on every node; YAML is a superset of JSON, so one parse covers both |
+| front matter | the block is parsed the same way, with the line offset added back |
+| archieml | no ranges from the parser — the uuid probe below; registered by `mikser-io-aml` |
+| csv rows | synthetic entities with no file of their own; the row is located in the PARENT csv by its key; registered by `mikser-io-csv` |
+| remote (`gdrive://`, `github://`, …) | read through `readEntityContent`, so the provider dispatch applies as everywhere else |
+| assets | none — meta is synthesized, so no source position exists |
+
+`registerProvenanceFormat(name, { test, positions })` adds one; `probeFormat(name,
+{ test, parse })` is the shortcut for a parser that reports no ranges. Later
+registrations win. A format that ships in its own package registers there — the
+engine has no business knowing archieml exists.
+
+**The probe**, for a parser with no ranges: substitute a unique token for every
+value, re-parse **once** with the format's own parser, and read each position
+off wherever its token actually landed. This is mikser 4.x's `plugins/guide.js`
+mechanism with the thing that killed it removed — it re-parsed once per FIELD
+and needed worker processes and a disk cache to survive that. Positions are
+read from where tokens landed rather than from assuming a substitution matched
+the intended field, so a repeated value cannot produce a confidently wrong
+answer. There is no regex over the value, so its size is irrelevant.
+
+Nothing is injected into the output. The predecessor printed provenance into
+HTML comments for a browser script to turn into tooltips, which is why it was
+only ever safe in development — it changed the bytes that ship. The consumer
+here is an editing agent, which never looks at rendered bytes, so the answer is
+returned as data instead: `mikser_which` for "what produced this output", and
+`mikser_read_entity({ include: ["positions"] })` for "where is this value
+written".
+
 ### `layouts.inspect()`
 
 Exposed by `mikser-io-layouts` at `runtime.options.layouts.inspect(id)`.

package/index.js

@@ -13,6 +13,8 @@ export * from './src/journal.js'
 export * from './src/catalog.js'
 export * from './src/refs.js'
 export * from './src/manifest.js'
+export * from './src/provenance.js'
+export * from './src/tools.js'
 export * from './src/track.js'
 export * from './src/subscriptions.js'
 export * from './src/config.js'

package/package.json

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

package/src/auth.js

@@ -138,14 +138,22 @@ export async function authorize(req, verifier, { allowRemote = false, trustLoopb
             // 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)
+            // Named fields rather than a spread: a refinement must not be
+            // able to reach `ok` or `principal`, and listing what may cross
+            // is how that stays true when someone adds a field later.
+            // `scope` is load-bearing on an insufficient_scope challenge —
+            // RFC 6750 §3.1 puts the capability the caller lacks in it, and
+            // without it the client is told it is unauthorized but not for
+            // what.
+            const { status, code, description, scope } = verifier.rejectionFor?.(req) ?? {}
             return {
                 ok: false,
-                status: refined?.status ?? 401,
+                status: status ?? 401,
                 reason: 'invalid',
-                code: refined?.code ?? 'invalid_token',
-                description: refined?.description,
-                error: refined?.description ?? 'Invalid credential',
+                code: code ?? 'invalid_token',
+                description,
+                scope,
+                error: description ?? 'Invalid credential',
             }
         }
         // Nothing presented. No `code`: RFC 6750 §3.1 says a challenge to a

package/src/builtin-tools.js

@@ -0,0 +1,170 @@
+// The engine's own diagnostics, registered as tools.
+//
+// `explain()`, `manifest.verify()` 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.
+//
+// Registering them here fixes the direction: they exist on a bare engine, the
+// CLI flags become renderings of them rather than parallel implementations,
+// and the mcp plugin exposes them over a session without owning them.
+//
+// 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
+// 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
+// session — the boundary where it is actually needed.
+//
+// Schemas are declared in a neutral vocabulary rather than zod, because the
+// engine does not depend on zod and should not: the registry is transport
+// agnostic. `mikser-io-mcp` converts these to zod at bind time. The vocabulary
+// is deliberately small — a name, a type, whether it is required, a
+// description — since anything richer would be a schema language, and the
+// engine has no business owning one.
+
+import runtime from './runtime.js'
+import { registerTool } from './tools.js'
+import { buildReport, cycleHistory } from './report.js'
+
+// The MCP content envelope, so a CLI caller and a session caller see the same
+// bytes. Built here rather than imported from the plugin, because the plugin
+// is the thing that must not be required.
+const ok = (data) => ({
+    content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }],
+})
+const fail = (message) => ({ isError: true, content: [{ type: 'text', text: message }] })
+
+export function registerBuiltinTools() {
+    registerTool(
+        'explain',
+        {
+            description:
+                'Explain ONE entity: which layout claimed it and why, its destination, which inputs moved since it '
+                + 'last rendered, every dependency edge with what it resolved to, whether its last render attempt '
+                + 'threw, and a verdict on whether a build would re-render it. Accepts an id, a meta.href, or an id '
+                + 'without its extension. The first thing to reach for when a page will not rebuild and nothing says '
+                + 'why. Compares the CATALOG against the manifest, so an edit not yet imported reports as "source '
+                + 'differs from the catalog".',
+            inputSchema: {
+                reference: { type: 'string', required: true,
+                    description: 'Entity id, meta.href, or id without its extension.' },
+            },
+        },
+        async ({ reference }) => {
+            try {
+                // Imported here rather than at module scope: explain.js pulls
+                // in the formatter and the manifest, and a build that never
+                // asks should not pay for them.
+                const { explain } = await import('./explain.js')
+                // found:false is an answer, not a failure — it carries a hint
+                // about why nothing matched, which is the useful half when a
+                // caller has guessed at an id.
+                return ok(await explain(reference))
+            } catch (err) {
+                return fail(err.message)
+            }
+        },
+    )
+
+    registerTool(
+        'verify',
+        {
+            description:
+                'Check the output folder against what the manifest recorded: files missing, files whose bytes no '
+                + 'longer match, snapshots with no recorded hash, files on disk no snapshot claims, and destinations '
+                + 'claimed by more than one entity. Answers "is what is deployed what mikser thinks it produced". '
+                + 'Does not build or write anything.',
+            inputSchema: {},
+        },
+        async () => {
+            try {
+                if (!runtime.manifest?.verify) return fail('No manifest available — nothing to verify 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()),
+                })
+            } catch (err) {
+                return fail(err.message)
+            }
+        },
+    )
+
+    registerTool(
+        'sources',
+        {
+            description:
+                'Reverse lookup: what SOURCE entities produced this built destination, and how each one got there. '
+                + 'Read from the engine\'s refClosure — its own record of what a render consumed — so a bundle '
+                + 'assembled from a catalog query resolves to the actual parts that went in, each tagged with the '
+                + 'route that reached it (layout, partial, ref, or the recorded query it matched).\n\n'
+                + 'More than one claimant means a destination collision; the sources of all of them are unioned, and '
+                + '`explain` names the competitors. To locate a STRING or a CSS selector inside these sources, '
+                + 'use `which` (mikser-io-mcp), which answers this question and then searches the answer.',
+            inputSchema: {
+                destination: { type: 'string', required: true,
+                    description: 'Output-relative destination, e.g. "/bg/styles/site.css".' },
+            },
+        },
+        async ({ destination }) => {
+            try {
+                if (!destination) return fail('destination is required')
+                if (!runtime.manifest?.snapshotsAt) {
+                    return fail('No manifest available — nothing has been rendered yet.')
+                }
+                const { sourcesOf } = await import('./manifest.js')
+                const claimants = runtime.manifest.snapshotsAt(destination).map(snap => snap.id)
+                const sources = await sourcesOf(destination)
+                return ok({
+                    destination,
+                    claimants,
+                    sources,
+                    count: sources.length,
+                    // An empty list reads as "nothing produced this", when the
+                    // usual cause is a file COPIED there by the files/shares/
+                    // data plugins, which write without a render snapshot.
+                    ...(claimants.length ? {} : {
+                        hint: 'No render claims this destination. It may be a file copied there without a render '
+                            + 'snapshot, or the path may be wrong.',
+                    }),
+                    ...(claimants.length > 1 ? {
+                        contested: 'More than one entity renders here — see the `explain` tool. The sources below are '
+                            + 'the union of what all of them consumed.',
+                    } : {}),
+                })
+            } catch (err) {
+                return fail(err.message)
+            }
+        },
+    )
+
+    registerTool(
+        'build_report',
+        {
+            description:
+                'What a build cycle did, and why: entities rendered (each with a reason — inputs-changed, '
+                + 'ref-changed, query-matched, retry-failed — and the detail behind it), skipped, rendered-but-'
+                + 'byte-identical, renders that threw, warnings, and a count of entities gated at import. Each '
+                + 'report carries the cycleId it describes. Pass cycles: N for the last N FINISHED cycles, newest '
+                + 'first; history keeps the last 10 of this process.',
+            inputSchema: {
+                cycles: { type: 'number',
+                    description: 'How many finished cycles to return, newest first. Omit for the current one.' },
+            },
+        },
+        async ({ cycles }) => {
+            try {
+                if (cycles) return ok({ reports: cycleHistory(cycles) })
+                return ok(buildReport())
+            } catch (err) {
+                return fail(err.message)
+            }
+        },
+    )
+}

package/src/database/index.js

@@ -28,6 +28,7 @@ import path from 'node:path'
 import { mkdirSync, unlinkSync, existsSync } from 'node:fs'
 import Database from 'better-sqlite3'
 import runtime from '../runtime.js'
+import { isReportOnlyRun } from '../tools.js'
 import { onLoaded } from '../lifecycle.js'
 import packageInfo from '../../package.json' with { type: 'json' }
 
@@ -288,8 +289,24 @@ export function createSqliteDatabase({
         const currentConfig = runtime.options.configChecksum ?? null
         const configChanged = Boolean(recordedConfig && currentConfig && recordedConfig !== currentConfig)
 
+        // Report-and-exit invocations never rebuild, so wiping for them
+        // destroys the very state they were asked to describe — and then they
+        // answer from the empty cache as though that were the answer. Measured:
+        // one `--tool mikser_query_entities` after a config edit dropped 521
+        // entities and replied `total: 0`, which reads as "there are none".
+        //
+        // The staleness is real and still worth saying out loud; what is wrong
+        // is doing something irreversible about it on a read.
+        const reportOnly = isReportOnlyRun()
+
         let upgradedFromVersion = null
-        if (configChanged && !(recorded && recorded !== version)) {
+        if (reportOnly && ((recorded && recorded !== version) || configChanged)) {
+            logger?.warn(
+                'The cache is stale (%s changed since it was written) and this is a read-only run, '
+                + 'so it was NOT wiped — the answer below describes the last build, which may not '
+                + 'match your sources. Run a build to refresh it.',
+                configChanged ? 'config' : 'schema version')
+        } else if (configChanged && !(recorded && recorded !== version)) {
             logger?.warn(
                 'Config changed since the last run. Wiping the cache and rebuilding from sources ' +
                 '(files are the source of truth — no source data is affected). Note this tracks the ' +
@@ -297,7 +314,7 @@ export function createSqliteDatabase({
                 runtime.options.config,
             )
         }
-        if ((recorded && recorded !== version) || configChanged) {
+        if (!reportOnly && ((recorded && recorded !== version) || configChanged)) {
             // Schema mismatch on upgrade or downgrade. Per ADR-0002 the
             // files on disk are the source of truth and this database
             // is a derived cache, so the right behavior is to wipe the