mikser-io 11.14.1 → 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.1",
+  "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: [] }