mikser-io 11.7.0 → 11.8.0

package/docs/diagnostics.md

@@ -1044,6 +1044,7 @@ distinction is the whole of [Faults](#faults) above.
 | Code | Severity | Means |
 | --- | --- | --- |
 | `config-coverage-partial` | warn | This Node build has no module loader hooks, so the config stamp covers the entry file alone. Editing an imported module will not invalidate the cache. |
+| `config-stale-in-process` | warn | A config file changed on disk while `--watch` is running. Node has the module cached and config is only read at startup, so this rebuild and every one after it uses the logic the process booted with. Restart to pick it up. |
 | `durable-open` | error | The durable store could not be opened. Auth grants and the change-set log are unavailable. |
 | `durable-migration` | error | A registered migration failed. |
 | `durable-gitignore` | error | The durable store could not be added to `.gitignore` — it holds credentials and the working folder is usually a repo. |
@@ -1063,6 +1064,7 @@ distinction is the whole of [Faults](#faults) above.
 
 | Code | Severity | Means |
 | --- | --- | --- |
+| `source-content-not-text` | warn | A `sources()` collection with `content: true` loaded a file whose bytes are not text. They are decoded as UTF-8 and stored mangled, and every consumer inherits that. Set `content: false` to catalogue the files by path instead — `entity.uri` still points at them. Once per collection. |
 | `observer-bad-uri` | warn | An observer's `uri` is not an absolute URL, so no webhook can be routed to it. |
 | `untracked-file-read` | warn | A template read a file outside every folder mikser takes entities from, so it has no entity and changing it invalidates nothing. |
 | `progress` | info | A long phase reporting where it has got to. See [Progress](#progress). |

package/package.json

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

package/src/instance.js

@@ -288,7 +288,7 @@ function configMismatch(theirs) {
 // configCoverage lists every local module the config graph pulled in, so a
 // stat over that list catches an edit to an imported module — which a
 // client-side checksum of the entry file would miss entirely.
-async function configStale() {
+export async function configStale() {
     const covered = runtime.options.configCoverage?.files ?? []
     if (!covered.length) return null
     const { stat } = await import('node:fs/promises')

package/src/manager.js

@@ -4,6 +4,7 @@ import cron from 'node-cron'
 import { onProcess, onFinalized } from './lifecycle.js'
 import { resetReport } from './report.js'
 import { useLogger } from './engine/index.js'
+import { configStale } from './instance.js'
 import { ACTION } from './constants.js'
 import { junkFilter } from './utils/index.js'
 
@@ -22,12 +23,52 @@ const tasks = []
 // would wipe it out of a one-shot build's report.
 function scheduleProcess() {
     clearTimeout(runtime.engine.processTimeout)
-    runtime.engine.processTimeout = setTimeout(() => {
+    runtime.engine.processTimeout = setTimeout(async () => {
+        await warnConfigStale()
         resetReport()
         runtime.process()
     }, 1000)
 }
 
+// Editing config/*.js while watching changes nothing, and says nothing.
+//
+// Node has the module cached, and the config stamp is only compared at
+// startup — that is where "Config changed since the last run. Wiping the
+// cache…" comes from. So a watch process keeps running the logic it booted
+// with, rebuilds happily, and reports green. Reported after it cost a
+// consumer several rounds: a derivation plugin they had already fixed kept
+// producing the old output, every symptom pointed at the data rather than at
+// the process, and they reported it as broken twice before finding it.
+//
+// The check already exists — instance.js compares mtimes across
+// configCoverage.files to refuse a forwarded command against drifted config.
+// It just never ran on this path, where no client is asking.
+//
+// A warning, not a reload: re-importing a config module does not re-run the
+// plugin registration that happened at boot, so a "reload" that only
+// refreshed the module would be a more convincing version of the same lie.
+// Restarting is the honest fix, and mikser_ping already reports `stale` for
+// packages installed since boot on exactly this reasoning.
+async function warnConfigStale() {
+    if (runtime.options.watch !== true) return
+    let changed = null
+    try {
+        changed = await configStale()
+    } catch { return }          // never let a diagnostic break the rebuild
+    if (!changed || changed === configStaleReported) return
+    configStaleReported = changed
+    useLogger().warn(
+        { code: 'config-stale-in-process', file: changed },
+        'Config changed on disk (%s) but this process is still running the version it started with — '
+        + 'Node has the module cached and config is only re-read at startup. This rebuild, and every one '
+        + 'after it, uses the OLD logic. Restart to pick it up.',
+        changed)
+}
+
+// One warning per file, so a watch session editing the same module in a loop
+// does not print it on every save — and a DIFFERENT file still speaks up.
+let configStaleReported = null
+
 export async function createdHook(name, context) {
     if (!runtime.started) return
 

package/src/source.js

@@ -44,7 +44,7 @@ import pMap from 'p-map'
 import runtime from './runtime.js'
 import { useLogger } from './engine/index.js'
 import { ACTION } from './constants.js'
-import { checksum as fileChecksum, checksumOf, junkIgnore } from './utils/index.js'
+import { checksum as fileChecksum, checksumOf, junkIgnore, looksTextual } from './utils/index.js'
 import { reportGated, reportChanged } from './report.js'
 import { findById, findEntities, checksumsByCollection } from './catalog.js'
 import { bypassReason } from './invalidation.js'
@@ -293,6 +293,39 @@ export function scanSummary({ cap, loaded, emitted = 0, skipped = 0, deleted = 0
  *     called per file; returned object is merged onto the base entity.
  *     Return null to skip a file.
  */
+// Collections already warned about a `content: true` binary. Module-level so
+// the warning survives across cycles — a watch rebuild re-reads the same
+// files, and repeating it every cycle is how a warning gets filtered out.
+const binaryWarned = new Set()
+
+// `content: true` is right for the CSS and template parts useSource was built
+// for, and wrong in silence for a binary. `toString('utf8')` never fails: it
+// substitutes U+FFFD and returns a string, so a 4 MB PDF becomes 4 MB of
+// mangled text and every consumer downstream inherits it.
+//
+// Reported by mikser-io-ocr, which sent one as a prompt and got back "Your
+// input exceeds the context window of this model" — an error that names the
+// document, so the reader goes and looks at the PDF rather than at the
+// collection's config.
+//
+// Returns whether it warned, so the decision is testable without reading logs.
+export function warnIfNotText(collection, name, bytes, logger) {
+    if (binaryWarned.has(collection)) return false
+    if (looksTextual(bytes.subarray(0, SNIFF_BYTES))) return false
+    binaryWarned.add(collection)
+    logger?.warn(
+        { code: 'source-content-not-text', collection, sample: name },
+        'Source %j has `content: true` but %j is not text — its bytes are being decoded as UTF-8 and stored ' +
+        'mangled. Set `content: false` on the collection to catalogue these files by path instead ' +
+        '(entity.uri still points at them).',
+        collection, name)
+    return true
+}
+
+// Same prefix the filesystem provider sniffs (src/utils/entity.js). Enough
+// to see a file header without decoding a whole document twice.
+const SNIFF_BYTES = 8 * 1024
+
 export function useSource(core, options) {
     const {
         runtime,
@@ -559,6 +592,20 @@ export function useSource(core, options) {
             // Decoded from the bytes the checksum was taken over — not
             // re-read. See the gate above.
             base.content = bytes.toString('utf8')
+
+            // `content: true` is right for the CSS and template parts this
+            // was built for, and wrong in silence for a binary. toString
+            // never fails: it substitutes U+FFFD and hands back a string, so
+            // a 4 MB PDF becomes 4 MB of mangled text and every consumer
+            // downstream inherits it. Reported by mikser-io-ocr, which sent
+            // one as a prompt and got back "Your input exceeds the context
+            // window of this model" — an error that names the document and
+            // sends the reader to the PDF rather than to this line.
+            //
+            // Once per collection, not per file: a media folder catalogued
+            // this way is all binaries, and the fix is one setting either
+            // way.
+            warnIfNotText(collection, name, bytes, logger)
         }
         try {
             const extra = await load({ file, name, relativePath, entity: base })