mikser-io 11.14.0 → 11.15.0

package/docs/api-reference.md

@@ -415,6 +415,44 @@ const entity = await findEntity({ id: '/documents/post.md' })
 const entity = await findEntity(e => e.meta?.featured === true)
 ```
 
+### `findRef(ref, scope?)`
+
+Resolves a `$`-ref string — an id, a `meta.href`, a `meta.url`, or an id
+minus its extension — to one entity, or `null`.
+
+With a `scope`, it resolves **within** that scope first, then falls back to a
+target that is **outside the scope entirely** (every scoped key absent):
+
+```js
+// A $-ref from a Bulgarian page finds the Bulgarian target…
+const target = await findRef(ref, { 'meta.lang': 'bg' })
+```
+
+That is the multilingual case it exists for. Scoping a ref lookup by language
+is load-bearing — without it a page referencing an untranslated document
+silently resolves to another language's copy — but it also excludes data that
+is imported *once* because it has no language: a price list, a specification
+table, a taxonomy. The fallback reaches exactly those and nothing else. An
+untranslated document *has* a language, just the wrong one, so it stays
+unresolved and still warns.
+
+Pass the scope as a plain sift fragment; `findRef` knows nothing about
+language, and a tenant or a brand works the same way. Resolution is
+deterministic: the fallback asks for the absent key rather than taking any
+match and inspecting it, so a ref matching both a neutral row and a
+language-specific document always resolves to the neutral one.
+
+For **strict** scoping with no fallback, build the filter directly:
+
+```js
+const target = await findEntity({ ...refFilter(ref), 'meta.lang': lang })
+```
+
+Note that resolution is separate from invalidation. The `$`-ref edge in
+`mikser_refs` is recorded by core language-blind, so an edited target
+re-renders every page referencing it whatever scope the resolver used — which
+is why a `$`-ref beats looking a row up by key in a sidecar.
+
 ### `findEntities(query?)`
 
 Returns an array of all entities matching the query. Returns all entities

package/package.json

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

package/src/catalog.js

@@ -746,10 +746,55 @@ export async function* iterateEntities(query) {
 // references (ADR-0007). Used by the api plugin's HTTP handlers,
 // mikser-io-mcp's tools, and any library-mode caller.
 
-async function findRef(ref) {
+// Resolve a ref string to one entity, optionally WITHIN a scope.
+//
+// A multilingual catalog resolves a `$`-ref inside the asking document's
+// language — `{ ...refFilter(ref), 'meta.lang': lang }` — and that scoping is
+// load-bearing: without it a Bulgarian page referencing an untranslated
+// document silently resolves to the English one, and "unresolved ref" is the
+// signal that a translation is missing.
+//
+// It also makes shared data unreachable. Data imported ONCE because it has no
+// language — a price list, a specification table, a taxonomy — carries no
+// `meta.lang` at all, so a scoped filter excludes it on every build. Importing
+// it per language instead means maintaining the same rows three times.
+//
+// So: the scope first, then a target that is outside the scope ENTIRELY. That
+// narrowing is what keeps the guard. An untranslated document HAS a language,
+// just the wrong one, so it still fails to resolve and still warns; only a
+// target with no language at all is reachable by fallback.
+//
+// The fallback asks for it. The shape that suggests itself —
+//
+//     const any = await findEntity(refFilter(ref))
+//     return any?.meta?.lang == null ? any : null
+//
+// — is a different query: it takes an ARBITRARY match among every language and
+// then inspects it, so a ref matching both a language-neutral row and a
+// language-specific document resolves to whichever row came back, and the
+// neutral one becomes unreachable at random. Asking for the absent key is
+// deterministic, and `meta.lang` is an indexed column, so it is also cheap.
+//
+// `scope` is a plain sift fragment and this knows nothing about language:
+// `{ 'meta.lang': lang }` is one use, a tenant or a brand is another. The
+// language lives at the call site, which is the only place that knows the
+// asking document.
+//
+// A caller that wants STRICT scoping, with no fallback, writes the filter
+// directly — `findEntity({ ...refFilter(ref), ...scope })` — which is exactly
+// what it wrote before this existed.
+export async function findRef(ref, scope) {
     if (!ref || typeof ref !== 'string') return null
-    const matches = await findEntities(refFilter(ref))
-    return matches[0] ?? null
+    const filter = refFilter(ref)
+    const scopeKeys = scope ? Object.keys(scope) : []
+    if (!scopeKeys.length) return (await findEntities(filter))[0] ?? null
+
+    const scoped = await findEntities({ ...filter, ...scope })
+    if (scoped.length) return scoped[0]
+
+    // Outside the scope entirely: every scoped key absent.
+    const unscoped = Object.fromEntries(scopeKeys.map(key => [key, { $exists: false }]))
+    return (await findEntities({ ...filter, ...unscoped }))[0] ?? null
 }
 
 function expandLimits() {

package/src/database/sift-to-sql.js

@@ -49,7 +49,20 @@ const TRANSLATABLE_OPS = new Set([
 
 function sqlForOp(column, op, value) {
     switch (op) {
-        case '$eq':  return { sql: `${column} = ?`,  params: [value] }
+        case '$eq':
+            // NULL-safe equality. `column = NULL` is NULL in SQL, never
+            // true, so this pushed down as a clause that matched NOTHING —
+            // while sift reads `{field: null}` as "null or absent" and
+            // matches both. The filter was translatable, so there was no
+            // jsFilter left behind to correct it: the query simply returned
+            // no rows. `$ne` has been null-safe since it was written; this
+            // is the same care on the other side of it.
+            //
+            // An absent key and an explicit null are the same NULL in an
+            // indexed column, so IS NULL is exactly sift's answer here.
+            return value === null
+                ? { sql: `${column} IS NULL`, params: [] }
+                : { sql: `${column} = ?`,  params: [value] }
         case '$ne':  // NULL-safe inequality — IS NOT for null, != otherwise
             return value === null
                 ? { sql: `${column} IS NOT NULL`, params: [] }

package/src/instance.js

@@ -31,7 +31,8 @@ import { createHash } from 'node:crypto'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import { existsSync, unlinkSync } from 'node:fs'
-import { chmod } from 'node:fs/promises'
+import { chmod, stat } from 'node:fs/promises'
+import { checksum } from './utils/index.js'
 
 import runtime from './runtime.js'
 import { onLoaded } from './lifecycle.js'
@@ -288,23 +289,55 @@ 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.
+// Has a config file CHANGED since this instance started?
+//
+// Content, not mtime. A `git rebase`, `git checkout` or `rsync` rewrites a
+// file with byte-identical content and a new mtime, and the instance then
+// refused every forwarded command — "this instance's config changed on disk
+// since it started" — while `git diff HEAD` reported nothing. Twice in one
+// afternoon on one machine.
+//
+// On production the cost is not a restart. The config checksum is what the
+// cache is stamped with, so a config the engine believes has moved buys a
+// full cold re-derive of every asset, which is how a no-op rebase turns into
+// twenty minutes of ffmpeg.
+//
+// mtime is kept as a PRE-FILTER, not as the answer: it is a stat against a
+// read, and in the ordinary case nothing has moved and nothing is read. Only
+// a file whose mtime shifted gets hashed, and only a file whose CONTENT
+// shifted is reported. A file rewritten identically has its stamp refreshed
+// so the next check is cheap again.
+async function configFingerprint(file) {
+    try {
+        return { mtime: (await stat(file)).mtimeMs, hash: await checksum(file) }
+    } catch {
+        // Deleted, or unreadable. A stable sentinel, so a file that is still
+        // missing on the next check does not read as having changed again.
+        return { mtime: 0, hash: null }
+    }
+}
+
 export async function configStale() {
     const covered = runtime.options.configCoverage?.files ?? []
     if (!covered.length) return null
-    const { stat } = await import('node:fs/promises')
     const stamps = runtime.options.configStamps
     if (!stamps) {
         // First call: record, do not judge. Nothing to compare against yet.
         runtime.options.configStamps = Object.fromEntries(
-            await Promise.all(covered.map(async (file) => {
-                try { return [file, (await stat(file)).mtimeMs] } catch { return [file, 0] }
-            })))
+            await Promise.all(covered.map(async (file) => [file, await configFingerprint(file)])))
         return null
     }
     for (const file of covered) {
-        let now = 0
-        try { now = (await stat(file)).mtimeMs } catch { /* deleted counts as changed */ }
-        if (stamps[file] !== now) return file
+        const was = stamps[file]
+        const now = await configFingerprint(file)
+        if (was?.mtime === now.mtime) continue          // nothing touched it
+        if (was?.hash === now.hash) {
+            // Touched and identical — a checkout, a rebase, a sync. Not a
+            // change, and re-stamped so this file is a stat again next time.
+            stamps[file] = now
+            continue
+        }
+        return file
     }
     return null
 }