mikser-io 9.59.2 → 9.61.1

package/CLAUDE.md

@@ -158,7 +158,12 @@ brevity.
 - `server.js` — Express bring-up: CLI flags (`--server`, `--cors`,
   `--no-cors`), trust-proxy, CORS (with extensible header arrays for
   plugins to push onto), late-binding static mount + listen.
-- `report.js` — the `--json` build report. `warnings` is a VIEW of
+- `report.js` — the `--json` build report. `invalidated` says WHY the
+  build did work (`nothing` / `sources` / `config` / `version` / `clear`),
+  recorded where each is decided — `reportWipe` in database/index.js,
+  `reportChanged` in source.js as the complement of `reportGated`.
+  `evaluated` is what a subsystem looked at vs what exists
+  (`reportEvaluated`), generalised from assets' matchTally. `warnings` is a VIEW of
   `logger.warn`; `faults` is a view of `logger.error` **carrying a
   `code`** — a subsystem declaring it cannot work, deduped by that code,
   never cleared per cycle, and surfaced in `mikser_ping`. The log call is
@@ -190,6 +195,11 @@ brevity.
   over ids, not the matched paths, so a file appearing later still
   invalidates. Paths resolve against `options.workingFolder` — the
   render-time `runtime` is a per-render projection with no options on it.
+  The "this file has no entity" warning reads `options.sourceFolders` —
+  the set useSource records as it registers each collection — NOT a list
+  of folder names written in the plugin. A hardcoded list misses every
+  collection a project registers through `sources()`, which produced 63
+  false warnings per build on a real site.
 - `render.js` / `postprocess.js` — Piscina worker entry points AND the
   default-export functions the INLINE/SERIAL dispatcher calls directly.
   Each receives entity + options + config + state; the WORKER path also
@@ -205,7 +215,12 @@ brevity.
   `descriptor.options` and arrive as the `config` arg to
   `load`/`render`/`setup`/`postprocess`/`teardown`.
 - `config.js` — loads `mikser.config.js` at `onLoad` into
-  `runtime.config`. v9 holds only engine-level keys (`server`,
+  `runtime.config`. The cache-invalidating stamp covers the config's whole
+  local module graph, captured via `module.registerHooks` during the import
+  (Node 22.15+; older runtimes fall back to the entry file and warn). Scoped
+  to the config's own directory — `node_modules` alone is not enough of a
+  filter, because a workspace symlinks its siblings outside it. Coverage is
+  published at `runtime.options.configCoverage` and in the build report. v9 holds only engine-level keys (`server`,
   `logging`, `catalog` if tuned) plus the `plugins` array — all
   plugin options moved to the factory call site (ADR-0010).
 - `plugins.js` — dispatches v9 plugin entries at `onLoad`. Each

package/docs/diagnostics.md

@@ -26,6 +26,9 @@ engine source, the entry point is missing and belongs on this page.
 | 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) |
 | A tool answered emptily — is it broken, or is there nothing to find? | [`faults`](#faults) |
+| I edited the build and nothing rebuilt | `--json` → `config.files` |
+| Why did this build do any work at all? | `--json` → `invalidated` |
+| Did my new pattern get a chance to match? | `--json` → `evaluated` |
 
 ## Command line
 
@@ -150,6 +153,33 @@ The buckets, and the distinction between them is the point:
 | `warnings` | everything that went through `logger.warn` this cycle, with its `code` |
 | `faults` | subsystems that reported they **cannot work** — see [Faults](#faults) |
 
+`invalidated` says why the build did anything, which the counts never did —
+`0 rendered` reads the same whether nothing needed doing or something did and
+the engine failed to notice:
+
+| cause | means |
+| --- | --- |
+| `nothing` | the engine looked and there was no work. A finding, not an absence — check `summary.gated` to see how much it looked at |
+| `sources` | these files changed, named in `changed` (capped, with `truncated` when there were more) |
+| `config` | the config or a module it imports moved, so the cache was wiped |
+| `version` | the engine version moved, with `from` and `to` |
+| `clear` | you passed `--clear` |
+
+A wipe outranks changed sources: once the cache goes, every file is a changed
+file and listing them all is noise.
+
+`evaluated` says what each subsystem actually looked at, against what exists —
+`{ assets: { evaluated: 0, of: 397 } }`. A new pattern that never had the
+chance to match anything otherwise looks exactly like a run with nothing to do.
+
+Each report also carries `config`: the files the config stamp spans, and
+whether that coverage is `complete`. The stamp is what makes a config edit
+invalidate the cache, and it covers the config's whole local module graph —
+not just the entry file. So if you keep the build in `config/pipeline.js` and
+import it from both a dev and a prod config, editing the pipeline invalidates,
+which is the case that matters. `config.files` is there so *"I edited the build
+and nothing rebuilt"* is answerable by reading rather than by experiment.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.59.2",
+  "version": "9.61.1",
   "description": "A mixer for content: entities in, configurable render pipelines, outputs of any kind. Static sites are the canonical recipe, not the definition — the same engine renders PDFs, emails and whatever a renderer plugin produces. Files are the source of truth, every lifecycle phase is observable, and the build graph is queryable by an agent.",
   "main": "index.js",
   "exports": {

package/src/catalog.js

@@ -536,6 +536,33 @@ export async function findEntities(query) {
     return shim.all().filter(m)
 }
 
+// How many entities match, without materializing any of them.
+//
+// findEntities parses the JSON body of every row it returns, which is the
+// wrong price for a number. A COUNT(*) with the same pushed-down WHERE is one
+// query and no parsing — the difference between asking "how big is the
+// catalog" costing nothing and costing a full scan.
+//
+// Returns null when the query cannot be answered in SQL alone. A residual
+// JS-side clause would require fetching the rows to test them, which is
+// exactly what this exists to avoid, and guessing a number would be worse than
+// admitting there isn't one.
+export function countEntities(query) {
+    if (!db?.isOpen) {
+        const shim = mapStub()
+        if (!shim) return 0
+        if (!query) return shim.all().length
+        const m = typeof query === 'function' ? query : sift(query)
+        return shim.all().filter(m).length
+    }
+    if (!query) return stmtCount.get().c
+
+    const t = siftToSql(query)
+    // A residual matcher means part of the filter never reached SQL.
+    if (residualMatcher(query, t.jsFilter)) return null
+    return db.prepare(`SELECT COUNT(*) AS c FROM mikser_entities ${t.sql}`).get(...t.params).c
+}
+
 // Streaming variant of findEntities. Same query shape, same sift→SQL
 // translation, but yields entities chunk-by-chunk so peak memory is
 // O(chunk × entity) instead of O(corpus × entity).

package/src/config.js

@@ -1,10 +1,74 @@
 import runtime from './runtime.js'
 import { useLogger } from './engine.js'
 import { onLoad } from './lifecycle.js'
-import { checksum } from './utils.js'
+import { checksum, checksumOf } from './utils.js'
 import path from 'node:path'
+import nodeModule from 'node:module'
+import { fileURLToPath } from 'node:url'
 import { existsSync } from 'node:fs'
 
+// Every local module the config actually pulls in, recorded as it loads.
+//
+// The stamp used to be the entry file's bytes alone, and that is inverted
+// against significance the moment a project has more than one config — which
+// is as soon as it has a dev one and a prod one. Both import the module that
+// decides how the site is built; neither IS that module. So a comment in the
+// thin wrapper wiped the catalog, and rewriting the pipeline that processes
+// every asset changed nothing and rebuilt nothing, on a green build.
+//
+// Node's own loader hook rather than parsing import statements. The resolver
+// already knows the answer exactly, including transitive imports and dynamic
+// ones that actually ran, and a regex over source is the kind of thing that
+// silently misses a case — which here means silently not invalidating, the
+// exact failure being fixed.
+//
+// Scoped to files under the config's own directory. `node_modules` is not
+// enough of a filter on its own: a workspace symlinks its siblings, so
+// `mikser-io` itself resolves to a real path outside node_modules and the
+// engine's entire source tree would land in the stamp.
+function captureConfigGraph(root) {
+    const files = new Set()
+    let capturing = false
+
+    // Node 22.15+. Older runtimes keep the previous behaviour rather than a
+    // worse guess, and `configCoverage` says which one is in force.
+    if (typeof nodeModule.registerHooks !== 'function') {
+        return { files, supported: false, start() {}, stop() {} }
+    }
+    nodeModule.registerHooks({
+        load(url, context, next) {
+            if (capturing && url.startsWith('file:')) {
+                const file = fileURLToPath(url)
+                if (!file.includes(`${path.sep}node_modules${path.sep}`)
+                    && !path.relative(root, file).startsWith('..')) {
+                    files.add(file)
+                }
+            }
+            return next(url, context)
+        },
+    })
+    return {
+        files,
+        supported: true,
+        start() { capturing = true },
+        stop() { capturing = false },
+    }
+}
+
+// One stamp over the whole set, path-qualified and order-independent.
+//
+// Path as well as content, so moving a module between two files with the same
+// bytes still counts as a change.
+async function stampGraph(files) {
+    const parts = []
+    for (const file of [...files].sort()) {
+        try {
+            parts.push(`${file}:${await checksum(file)}`)
+        } catch { /* vanished between load and stat — the next cycle sees it */ }
+    }
+    return parts.length ? checksumOf(parts.join('\n')) : null
+}
+
 onLoad(async () => {
     const logger = useLogger()
     const configFile = path.resolve(runtime.options.config)
@@ -19,16 +83,10 @@ onLoad(async () => {
     // invalidation, so the only symptom was output that did not match the
     // config, with nothing saying so.
     //
-    // The file's bytes only. A config that imports other modules will not
-    // notice a change in those, which is a real limit worth knowing rather
-    // than a reason to hash the whole module graph.
-    try {
-        runtime.options.configChecksum = await checksum(configFile)
-    } catch {
-        // No config file is a legitimate state (defaults all the way down);
-        // absent stamp means "nothing to compare", not "changed".
-        runtime.options.configChecksum = null
-    }
+    // Computed AFTER the import, from what the import actually loaded — see
+    // captureConfigGraph. Before it, there is nothing to hash but the entry
+    // file, which is the bug.
+    const graph = captureConfigGraph(path.dirname(configFile))
 
     // Absence is decided by looking for the file, NOT by catching
     // ERR_MODULE_NOT_FOUND from the import.
@@ -48,14 +106,54 @@ onLoad(async () => {
         logger.debug('No config file at %s — using defaults', configFile)
     } else {
         // No catch: any failure loading a config that EXISTS is fatal.
-        const config = await import(configFile)
-        if (typeof config.default == 'function') {
-            runtime.config = await config.default(runtime)
-        } else if (typeof config.default == 'object') {
-            runtime.config = config.default
+        graph.start()
+        try {
+            const config = await import(configFile)
+            if (typeof config.default == 'function') {
+                runtime.config = await config.default(runtime)
+            } else if (typeof config.default == 'object') {
+                runtime.config = config.default
+            }
+        } finally {
+            graph.stop()
+        }
+    }
+
+    // The stamp, and what it covers.
+    //
+    // Coverage is published because "I edited the build and nothing rebuilt"
+    // was only answerable by experiment. It is the difference between a limit
+    // that is documented and one that is visible at the moment it bites.
+    //
+    // Absent stamp means "nothing to compare", not "changed" — no config file
+    // is a legitimate state, defaults all the way down.
+    const covered = [...graph.files]
+    runtime.options.configCoverage = {
+        files: covered.sort(),
+        // False on a runtime without loader hooks, where the stamp is the
+        // entry file alone and a change to anything it imports is invisible.
+        complete: graph.supported,
+    }
+    if (covered.length) {
+        runtime.options.configChecksum = await stampGraph(covered)
+        logger.debug('Config checksum spans %d file(s): %s', covered.length, covered.join(', '))
+    } else {
+        try {
+            runtime.options.configChecksum = existsSync(configFile) ? await checksum(configFile) : null
+        } catch {
+            runtime.options.configChecksum = null
         }
     }
 
+    // Said once, at the only moment it can be acted on. A project whose build
+    // lives in a module the stamp cannot reach gets a rebuild it did not ask
+    // for rather than silence it cannot diagnose.
+    if (existsSync(configFile) && !graph.supported) {
+        logger.warn({ code: 'config-coverage-partial' },
+            'This Node build has no module loader hooks, so the config stamp covers %s alone. Editing a module '
+            + 'it imports will NOT invalidate anything — run with --force after such a change.', configFile)
+    }
+
     // Nothing else is loaded. There is deliberately no `config/<plugin>
     // .config.js` channel: plugin options arrive as factory arguments
     // (ADR-0010), and an entry in `plugins` is a factory call result — a

package/src/database/index.js

@@ -47,6 +47,7 @@ import { mkdirSync, unlinkSync, existsSync, readFileSync, writeFileSync } from '
 import Database from 'better-sqlite3'
 import runtime from '../runtime.js'
 import { isReportOnlyRun } from '../tools.js'
+import { reportWipe } from '../report.js'
 import { onLoaded } from '../lifecycle.js'
 import packageInfo from '../../package.json' with { type: 'json' }
 
@@ -330,9 +331,9 @@ export function createSqliteDatabase({
                 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 ' +
-                'bytes of %s only: a change in a module it imports is not seen.',
+                'Config changed since the last run. Wiping the cache and rebuilding from sources '
+                + '(files are the source of truth — no source data is affected). The stamp covers %s and '
+                + 'every local module it imports; `--json` reports exactly which files under `config.files`.',
                 runtime.options.config,
             )
         }
@@ -355,6 +356,15 @@ export function createSqliteDatabase({
             } else if (forceWipe) {
                 logger?.info('Clearing the cache and rebuilding from sources.')
             }
+            // Recorded where the decision is made. The report otherwise shows
+            // a cold build and no reason for it, and "everything rebuilt" is
+            // the same output whether the version moved, the config moved, or
+            // someone passed --clear.
+            reportWipe(
+                recorded && recorded !== version ? 'version' : forceWipe ? 'clear' : 'config',
+                recorded && recorded !== version ? { from: recorded, to: version } : {},
+            )
+
             // Unlink, rather than dropping table by table.
             //
             // The wipe used to have to know which tables to keep, because

package/src/plugins/assets.js

@@ -1,3 +1,5 @@
+import { reportEvaluated } from '../report.js'
+import { countEntities } from '../catalog.js'
 import path from 'node:path'
 import { mkdir, writeFile, unlink, rm, readFile, symlink, } from 'fs/promises'
 import { existsSync } from 'node:fs'
@@ -482,6 +484,24 @@ export function assets(options = {}) {
 
         reportUnmatchedPresets(logger)
 
+        // How much of the catalog this run actually looked at.
+        //
+        // The warning above only fires on a full cycle, because on an
+        // incremental one a healthy preset legitimately matches nothing. That
+        // is correct and it leaves the reverse question unanswered: a NEW
+        // pattern that never had the chance to match anything looks exactly
+        // like a run with nothing to do. `evaluated 4 of 397` answers it
+        // without needing a warning to decide whether to fire.
+        try {
+            // COUNT(*), not a fetch: the denominator is a number, and paying a
+            // full scan and a JSON.parse per row to produce it would make the
+            // diagnostic cost more than the thing it diagnoses.
+            reportEvaluated('assets', {
+                evaluated: matchTally.evaluated,
+                of: countEntities({ collection: { $ne: collection } }),
+            })
+        } catch { /* a count is not worth failing a build over */ }
+
         let revisions = await globby('**/*.md5', { cwd: runtime.options.assetsFolder })
         for (let revision of revisions) {
             const [preset] = revision.split(path.sep)

package/src/plugins/render/file.js

@@ -67,16 +67,27 @@ function entityIdFor(workingFolder, resolved) {
 // nothing to track" read identically from a template. Said once per path.
 const warnedOutside = new Set()
 function warnIfUntrackable(options, resolved, logger) {
-    const folders = ['documentsFolder', 'filesFolder', 'assetsFolder', 'resourcesFolder', 'dataFolder']
-        .map(key => options?.[key]).filter(Boolean)
-    if (!folders.length) return  // nothing configured to compare against
+    // Every folder whose files become entities, as recorded by useSource when
+    // it registered them — NOT a list written here.
+    //
+    // The first version of this hardcoded five content folders, and a project
+    // registering its own collections through sources() has more than five. On
+    // lmed that meant 63 warnings per build, one for every stylesheet and
+    // script, all of them tracked correctly and every one of them saying the
+    // opposite. Which is worse than not warning: 63 spurious lines a build
+    // teaches you to filter the channel, and the filtered-out line is the real
+    // one.
+    const folders = Object.values(options?.sourceFolders ?? {})
+    // Nothing registered yet means nothing can be concluded. Silence is the
+    // only honest answer — the previous shape guessed instead.
+    if (!folders.length) return
     if (folders.some(folder => !path.relative(folder, resolved).startsWith('..'))) return
     if (warnedOutside.has(resolved)) return
     warnedOutside.add(resolved)
     logger?.warn?.({ code: 'untracked-file-read' },
-        'A template read %s, which is outside every content folder — so it has no entity, nothing watches it, '
-        + 'and changing it will NOT rebuild the pages that read it. Move it under a content folder if that '
-        + 'matters, or pass { track: false } to say the staleness is intended.', resolved)
+        'A template read %s, which is outside every folder mikser takes entities from — so it has no entity, '
+        + 'nothing watches it, and changing it will NOT rebuild the pages that read it. Register the folder '
+        + 'with sources() if that matters, or pass { track: false } to say the staleness is intended.', resolved)
 }
 
 export function load({ runtime, options, track, logger }) {

package/src/report.js

@@ -109,8 +109,12 @@ export function resetReport() {
     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.report = {
+        rendered: [], skipped: [], unchanged: [], errors: [], warnings: [], gated: 0, evaluated: {},
+    }
     runtime.state.renderErrors = []
+    // Per cycle, unlike the wipe: what changed is a fact about THIS build.
+    runtime.state.changed = { ids: [], count: 0 }
 }
 
 // End of a cycle: stamp it, file it, and wake anyone waiting on it.
@@ -136,10 +140,70 @@ function store() {
     // 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 }
+    runtime.state.report ??= {
+        rendered: [], skipped: [], unchanged: [], errors: [], warnings: [], gated: 0, evaluated: {},
+    }
+    runtime.state.report.evaluated ??= {}
     return runtime.state.report
 }
 
+// Why this cycle did any work at all.
+//
+// The counts say what happened; they never said what STARTED it. "0 rendered"
+// is the same line whether nothing needed doing, or something needed doing and
+// the engine could not tell — which is the difference between a build you can
+// trust and one you have to reproduce by hand.
+//
+// Two halves, because there are two ways work begins. A WIPE is process-level:
+// the version moved, the config moved, `--clear` was passed, and everything is
+// rebuilt from source. Otherwise it is the sources that changed since last
+// time, which is per cycle.
+//
+// `nothing` is a first-class answer, not an absence. It means the engine
+// looked and there was genuinely no work — which is the one thing an operator
+// most wants distinguished from a build that silently did not notice.
+
+// Set once, by whoever decided to wipe. Not gated on reportWanted: it happens
+// at database open, which may be before a reader has asked for a report, and
+// it is one small object.
+export function reportWipe(cause, detail = {}) {
+    runtime.state ??= {}
+    runtime.state.wipe = { cause, ...detail }
+}
+
+// One source whose bytes moved. The complement of reportGated: between them
+// every file the engine looked at is accounted for.
+export function reportChanged(id) {
+    if (!reportWanted() || !id) return
+    const store = changedStore()
+    store.count++
+    // Capped. On a cold build this is the whole corpus, and the cause already
+    // says so — the list is for the incremental case, where naming the three
+    // files that moved is the entire answer.
+    if (store.ids.length < CHANGED_LIMIT) store.ids.push(id)
+}
+
+const CHANGED_LIMIT = 50
+
+function changedStore() {
+    runtime.state ??= {}
+    runtime.state.changed ??= { ids: [], count: 0 }
+    return runtime.state.changed
+}
+
+// What a subsystem looked at, against what it could have looked at.
+//
+// Generalised from the assets plugin, which already warns when a configured
+// preset matched none of the entities a full cycle evaluated. That reasoning —
+// an incremental cycle only re-evaluates what changed, so matching nothing can
+// be perfectly healthy — is not specific to presets, and neither is the
+// question it answers. "assets evaluated 4 of 397" is the line that tells you
+// instantly that a new pattern never had the chance to match anything.
+export function reportEvaluated(scope, { evaluated, of } = {}) {
+    if (!reportWanted() || !scope) return
+    store().evaluated[scope] = { evaluated: evaluated ?? 0, ...(Number.isFinite(of) ? { of } : {}) }
+}
+
 // An entity whose SOURCE did not change is gated at import and never becomes
 // a render task at all — so it appears in neither `rendered` nor `skipped`,
 // and the two lists would not reconcile with the corpus size without saying
@@ -309,6 +373,25 @@ export function renderErrorCount() {
     return errorStore().length
 }
 
+// The cause, and enough detail to act on it.
+//
+// A wipe outranks changed sources: when the cache went, everything is a
+// changed source and saying so is noise. `nothing` is returned rather than
+// omitted, because an absent field reads as "not recorded" and this is a
+// finding.
+function invalidation() {
+    const wipe = runtime.state?.wipe
+    if (wipe) return wipe
+    const { ids, count } = changedStore()
+    if (!count) return { cause: 'nothing' }
+    return {
+        cause: 'sources',
+        changed: ids,
+        count,
+        ...(count > ids.length ? { truncated: count - ids.length } : {}),
+    }
+}
+
 export function buildReport() {
     const report = store()
     const cycle = runtime.state?.cycle
@@ -325,6 +408,18 @@ export function buildReport() {
         // failed build, whatever the other counts say.
         errors: errorStore(),
         warnings: report.warnings,
+        // Why this build did any work — see reportWipe / reportChanged.
+        invalidated: invalidation(),
+        // What each subsystem looked at, against what it could have.
+        ...(Object.keys(report.evaluated ?? {}).length ? { evaluated: report.evaluated } : {}),
+        // Which files the config stamp spans.
+        //
+        // "I edited the build and nothing rebuilt" was only answerable by
+        // experiment: the stamp covered the entry file, real projects put the
+        // build in a module it imports, and nothing said which. Published
+        // rather than documented, because a limit you can see at the moment it
+        // bites is a different thing from one written down elsewhere.
+        ...(runtime.options?.configCoverage ? { config: runtime.options.configCoverage } : {}),
         // Named conditions reported at error level: a subsystem saying it
         // cannot work, as opposed to `errors`, which is a render that threw.
         // Carried whole rather than filtered to this cycle — a fault raised at
@@ -345,6 +440,8 @@ export function buildReport() {
             gated: report.gated,
             warnings: report.warnings.length,
             faults: faults().length,
+            // Sources whose bytes moved this cycle. The complement of `gated`.
+            changed: changedStore().count,
         },
     }
 }

package/src/source.js

@@ -44,7 +44,7 @@ import pMap from 'p-map'
 import runtime from './runtime.js'
 import { ACTION } from './constants.js'
 import { checksum as fileChecksum, checksumOf, junkIgnore } from './utils.js'
-import { reportGated } from './report.js'
+import { reportGated, reportChanged } from './report.js'
 import { findById, findEntities, checksumsByCollection } from './catalog.js'
 import { useDatabase } from './database/index.js'
 
@@ -328,6 +328,18 @@ export function useSource(core, options) {
             ? folder
             : path.join(runtime.options.workingFolder, folder)
         runtime.options[`${collection}Folder`] = absFolder
+        // The authoritative set of folders whose files become entities.
+        //
+        // `<collection>Folder` above is the per-collection accessor and reads
+        // like one; this is the LIST, which is a different question and the
+        // one anything asking "could a file here be tracked?" needs. Deriving
+        // it by scanning options for a `*Folder` suffix would sweep up
+        // workingFolder, runtimeFolder and outputFolder, and hand-listing the
+        // content ones misses every collection a project registers itself —
+        // which is exactly how the file helpers came to warn 63 times a build
+        // about files they were tracking correctly.
+        runtime.options.sourceFolders ??= {}
+        runtime.options.sourceFolders[collection] = absFolder
         logger.debug('%s folder: %s', cap, absFolder)
 
         await mkdir(absFolder, { recursive: true })
@@ -456,6 +468,10 @@ export function useSource(core, options) {
             reportGated()
             return
         }
+        // Past the gate means the bytes are new or different — the complement
+        // of reportGated, so between them every file looked at is accounted
+        // for and "why did this build do anything" has an answer.
+        reportChanged(id)
 
         const base = {
             id,