mikser-io-layouts 2.8.0 → 2.9.2

package/lib/assembly.js

@@ -24,6 +24,7 @@ import {
     inputHashOf,
     createTrack,
     recordReads,
+    observeConsumed,
     queryContext,
     useDatabase,
 } from 'mikser-io'
@@ -255,7 +256,7 @@ export function createOnBeforeRender({
                 // plain JavaScript, so `row.meta?.hero?.tags` has no syntax
                 // for any template parser to find. Observing the read is the
                 // only way to know the key is required.
-                const sidecarTrack = createTrack({ partial: false, meta: true })
+                const sidecarTrack = createTrack({ partial: false, meta: true, consumed: true })
                 if (existsSync(sidecarPath)) {
                     try {
                         // Stamp = the shared sidecar digest, so the URL
@@ -289,9 +290,25 @@ export function createOnBeforeRender({
                             const observed = entity?.meta
                                 ? { ...entity, meta: recordReads(entity.meta, 'meta', sidecarTrack.metaRead) }
                                 : entity
+                            // Entities the sidecar PULLS IN are observed too,
+                            // each against its own id. A page reads
+                            // `items[].label` off a navigation document it
+                            // queried, and without this nothing records which
+                            // of that document's keys anyone actually needs —
+                            // so a document that never renders has no derivable
+                            // contract at all.
+                            const seenEntity = async (...args) =>
+                                observeConsumed(await findEntity(...args), sidecarTrack)
+                            const seenEntities = async (...args) => {
+                                const rows = await findEntities(...args)
+                                return Array.isArray(rows)
+                                    ? rows.map(row => observeConsumed(row, sidecarTrack))
+                                    : rows
+                            }
                             data = await queryContext.run(
                                 { entityId: entity.id, track: sidecarTrack },
-                                () => load({ entity: observed, findEntity, findEntities, runtime, signal }),
+                                () => load({ entity: observed, findEntity: seenEntity,
+                                             findEntities: seenEntities, runtime, signal }),
                             )
                         } catch (err) {
                             logger.error('Layout sidecar %s load() threw: %s', sidecarPath.replace(runtime.options.workingFolder + '/', ''), err.message)
@@ -381,7 +398,16 @@ export function createOnBeforeRender({
                                 postprocessors: entity.layout.postprocessors ?? (entity.layout.postprocessor ? [entity.layout.postprocessor] : []),
                                 tasks: entity.meta?.task || TASKS.INLINE,
                             }, { data, plugins, sidecarQueries: sidecarTrack.queries,
-                                 sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])] })
+                                 // Plain arrays, because this context is journaled as JSON
+                                 // before the render runs — a Set arrives as {}.
+                                 //
+                                 // That same round-trip is why these are what the
+                                 // SIDECAR read and nothing more: the recording
+                                 // views inside `data` do not survive it, so a key
+                                 // only the template touches is never recorded
+                                 // here. See check_entity's untraceable handling.
+                                 sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])],
+                                 sidecarConsumedReads: [...(sidecarTrack.consumedReads ?? [])].map(([k, v]) => [k, [...v]]) })
                         }
                     }
                 } else {
@@ -409,7 +435,16 @@ export function createOnBeforeRender({
                         // deleted. The paginated branch above already
                         // does this.
                         { data, plugins, sidecarQueries: sidecarTrack.queries,
-                          sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])] })
+                          // Plain arrays, because this context is journaled as JSON
+                                 // before the render runs — a Set arrives as {}.
+                                 //
+                                 // That same round-trip is why these are what the
+                                 // SIDECAR read and nothing more: the recording
+                                 // views inside `data` do not survive it, so a key
+                                 // only the template touches is never recorded
+                                 // here. See check_entity's untraceable handling.
+                                 sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])],
+                                 sidecarConsumedReads: [...(sidecarTrack.consumedReads ?? [])].map(([k, v]) => [k, [...v]]) })
                     }
                 }
             } // end per-layout for-loop

package/lib/inspect.js

@@ -23,7 +23,7 @@
 import { readFile } from 'node:fs/promises'
 
 export function createInspect({ runtime, findEntity, findEntities, useDatabase, collection }) {
-    return async function inspect(id, { samples = 3 } = {}) {
+    return async function inspect(id, { samples = 3, partials = null } = {}) {
         const layout = await findEntity({ id })
         if (!layout || layout.collection !== collection) {
             const err = new Error(`Layout not found: ${id}`)
@@ -67,6 +67,7 @@ export function createInspect({ runtime, findEntity, findEntities, useDatabase,
 
         const contract = await buildContract({
             layout, templateSource, runtime, findEntities, collection,
+            only: partials ? new Set(partials) : null,
         })
 
         return {
@@ -197,8 +198,13 @@ function safeParseReferences(renderer, source, templateName) {
 const MAX_DEPTH = 12
 const MAX_TEMPLATES = 200
 
-async function buildContract({ layout, templateSource, runtime, findEntities, collection }) {
+async function buildContract({ layout, templateSource, runtime, findEntities, collection, only }) {
     const consumes  = new Set()
+    // Read only behind a guard, anywhere in the tree. Kept apart from
+    // `consumes` so a caller can tell "the layout needs this" from "the layout
+    // uses this if it is there" — the difference between a document being wrong
+    // and a document being smaller.
+    const optional  = new Set()
     const templates = []
     const incomplete = []
     const visited   = new Set()
@@ -273,6 +279,7 @@ async function buildContract({ layout, templateSource, runtime, findEntities, co
             consumes.add(r)
             resolved.push(r)
         }
+        for (const v of parsed.optional ?? []) optional.add(resolve(v, subs))
         templates.push({ template: name, bindings, consumes: resolved.sort() })
 
         for (const p of parsed.partials ?? []) {
@@ -283,7 +290,18 @@ async function buildContract({ layout, templateSource, runtime, findEntities, co
             const partialName = isRich ? p.name : p
             if (!partialName) continue
 
+            // A partial that shares the caller's scope starts from it. In
+            // liquid that is `include` (as against `render`), and in handlebars
+            // every partial — the registry pattern depends on it, since the
+            // section name it dispatches on lives in the caller's loop.
+            // Inherited partials start from the scope they were included in,
+            // resolved through this template's own substitutions first.
             const childBindings = {}
+            if (isRich && p.inherits) {
+                for (const [name, path] of Object.entries(p.scope ?? {})) {
+                    childBindings[name] = resolve(path, subs)
+                }
+            }
             if (isRich) {
                 for (const [arg, path] of Object.entries(p.args ?? {})) {
                     childBindings[arg] = resolve(path, subs)
@@ -304,6 +322,19 @@ async function buildContract({ layout, templateSource, runtime, findEntities, co
                 incomplete.push({ template: partialName, reason: 'no layout entity has this name' })
                 continue
             }
+            // Scoped to what a particular render actually pulled in.
+            //
+            // A page layout that dispatches sections through a registry
+            // resolves STATICALLY to every section template in the project,
+            // because the `case` has a branch for each. Unscoped, the contract
+            // for a two-section page is the union of the whole catalogue and a
+            // real omission is one line in three hundred.
+            //
+            // The manifest already recorded which partials each render used, so
+            // the scope is observed rather than guessed. Skipping is silent by
+            // design: a branch this render did not take is not a gap in the
+            // contract, it is a part of the layout that does not apply.
+            if (only && !only.has(entity.id)) continue
             let childSource
             try {
                 childSource = await readFile(entity.uri, 'utf8')
@@ -329,17 +360,25 @@ async function buildContract({ layout, templateSource, runtime, findEntities, co
     // sidecar writes `document.meta.` and would have got an empty contract,
     // which reads exactly like a layout that needs nothing.
     const META_ROOT = /^[A-Za-z_$][\w$]*\.meta\./
+    const strip = (p) => (META_ROOT.test(p) ? p.replace(META_ROOT, '') : (p.startsWith('meta.') ? p.slice(5) : null))
     const meta = [...consumes]
         .map(p => (META_ROOT.test(p) ? p.replace(META_ROOT, '') : (p.startsWith('meta.') ? p.slice(5) : null)))
         .filter(Boolean)
 
     return {
         available: true,
+        // What the walk was allowed to reach. Null means the whole layout tree
+        // — every branch of every dispatch — which answers "what COULD this
+        // layout read" rather than "what does this page read".
+        scopedTo: only ? [...only].sort() : null,
         // False whenever ANY branch could not be read. A contract that looks
         // complete but silently omits a partial is the failure this exists to
         // prevent, so the flag leads and the reasons are named.
         complete: incomplete.length === 0,
         meta: [...new Set(meta)].sort(),
+        // The subset of `meta` a layout guards. A document missing one of these
+        // is not wrong — the template was written to work without it.
+        optionalMeta: [...new Set([...optional].map(strip).filter(Boolean))].sort(),
         consumes: [...consumes].sort(),
         templates,
         incomplete,

package/lib/mcp.js

@@ -129,49 +129,168 @@ function distance(a, b) {
 export function registerCheckTool({ runtime, findEntity, findEntities, useDatabase, collection, logger }) {
     const mcp = runtime.options.mcp
 
-    // Which layout this entity ACTUALLY rendered with, taken from its most
-    // recent snapshot rather than predicted.
-    //
-    // Layout selection has three mechanisms — declared meta.layout, a match
-    // pattern, and the auto-layout peel ladder — and re-deriving them here
-    // would be a second implementation to keep in step with the first. The
-    // manifest already recorded the answer.
-    const layoutFromSnapshot = (id) => {
+    const ok = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] })
+
+    // One read of the entity's most recent snapshot. Everything this tool knows
+    // about what actually happened comes from here.
+    const snapshotOf = (id) => {
         const db = useDatabase?.()
         if (!db?.handle) return null
-        const row = db.handle.prepare(
-            'SELECT refClosure FROM mikser_snapshots WHERE id = ? ORDER BY renderedAt DESC LIMIT 1',
-        ).get(id)
-        if (!row?.refClosure) return null
         try {
-            return JSON.parse(row.refClosure).find(e => e.kind === 'layout')?.target ?? null
-        } catch { return null }
+            return db.handle.prepare(
+                'SELECT refClosure, metaReads FROM mikser_snapshots WHERE id = ? ORDER BY renderedAt DESC LIMIT 1',
+            ).get(id) ?? null
+        } catch {
+            // A catalog written before metaReads existed. The static half of
+            // the contract still works; only the observed half is absent, which
+            // `reliable` already accounts for.
+            return db.handle.prepare(
+                'SELECT refClosure FROM mikser_snapshots WHERE id = ? ORDER BY renderedAt DESC LIMIT 1',
+            ).get(id) ?? null
+        }
     }
+    const parse = (json, fallback) => { try { return json ? JSON.parse(json) : fallback } catch { return fallback } }
+    const edgesOf = (snap) => parse(snap?.refClosure, [])
+    const readsOf = (snap) => parse(snap?.metaReads, [])
 
-    const readsFromSnapshot = (id) => {
+    // What every render read OFF this entity, and who read it.
+    //
+    // The contract for a document that never renders. `metaReads` answers "what
+    // did rendering THIS entity read"; this answers it from the other side —
+    // what does anything need FROM it — which is the only sense in which a data
+    // document has a contract at all.
+    const consumedContractOf = (id) => {
         const db = useDatabase?.()
-        if (!db?.handle) return []
-        const row = db.handle.prepare(
-            'SELECT metaReads FROM mikser_snapshots WHERE id = ? ORDER BY renderedAt DESC LIMIT 1',
-        ).get(id)
-        if (!row?.metaReads) return []
-        try { return JSON.parse(row.metaReads) } catch { return [] }
+        if (!db?.handle) return { keys: [], by: [] }
+        let rows = []
+        try {
+            rows = db.handle.prepare(
+                'SELECT id, consumedReads FROM mikser_snapshots WHERE consumedReads IS NOT NULL',
+            ).all()
+        } catch { return { keys: [], by: [] } }   // catalog predates the column
+        const keys = new Set(); const by = new Set()
+        for (const row of rows) {
+            for (const [cid, paths] of parse(row.consumedReads, [])) {
+                if (cid !== id) continue
+                by.add(row.id)
+                for (const path of paths) keys.add(path)
+            }
+        }
+        return { keys: [...keys].sort(), by: [...by].sort() }
+    }
+
+    // Compare what is consumed against what a document provides. Shared, so a
+    // data document is held to the same standard as a page — the only
+    // difference is where its contract came from.
+    const compare = (entity, consumedSet, optionalSet) => {
+        const provided = flattenMeta(entity.meta ?? {}, '', new Set())
+        const isUsed = (k) => consumedSet.has(k)
+            || [...consumedSet].some(c => c.startsWith(`${k}.`) || c.startsWith(`${k}[`))
+        const isProvided = (k) => provided.has(k)
+            || [...provided].some(x => x.startsWith(`${k}.`) || x.startsWith(`${k}[`))
+        const isOptional = (k) => optionalSet.has(k)
+            || [...optionalSet].some(o => k.startsWith(`${o}.`) || k.startsWith(`${o}[`))
+        const absent = [...consumedSet].filter(k => k && !isProvided(k))
+        const missing = absent.filter(k => !isOptional(k)).sort()
+        const missingOptional = absent.filter(isOptional).sort()
+        const candidates = [...provided]
+            .filter(k => !isUsed(k))
+            .filter(k => !ENGINE_KEYS.has(k.split('.')[0].replace(/\[\]$/, '')))
+            .sort()
+
+        // "The parent was read, and every child looks unused" is the signature
+        // of a read this engine cannot follow, not of dead data.
+        //
+        // Provenance is recorded where a value is READ off an entity. When that
+        // value is then handed on — a sidecar returning it to a template — the
+        // context carrying it is journaled as JSON in between, so the recording
+        // view does not survive and only the top-level access was ever seen. A
+        // form built from `enquiry.fields` shows `enquiry` consumed and every
+        // field beneath it apparently unused, on pages that visibly render it.
+        //
+        // Reporting those as unused is worse than saying nothing: someone
+        // acting on the list deletes a working form. They are collapsed under
+        // the ancestor that WAS read, and named for what they are — untraceable.
+        // Only when the ancestor was read and NOTHING under it was — "parent
+        // consumed, every child unused" is the signature.
+        //
+        // If any sibling IS consumed, the engine can evidently see inside that
+        // structure, so a key nobody read is real evidence and must stay in
+        // `unused`. Without this the safeguard would swallow the strongest
+        // signal the tool has: a typo like `hero.subtitile` sits under `hero`,
+        // which is certainly consumed.
+        const blind = (ancestor) => ![...consumedSet].some(c =>
+            c.startsWith(`${ancestor}.`) || c.startsWith(`${ancestor}[`))
+        const ancestorRead = (key) => {
+            let p = key
+            while (true) {
+                if (p.endsWith('[]')) p = p.slice(0, -2)
+                else if (p.includes('.')) p = p.replace(/\.[^.]+$/, '')
+                else return null
+                if (!p) return null
+                if (consumedSet.has(p)) return blind(p) ? p : null
+            }
+        }
+        const unused = []
+        const byAncestor = new Map()
+        for (const key of candidates) {
+            const under = ancestorRead(key)
+            if (!under) { unused.push(key); continue }
+            if (!byAncestor.has(under)) byAncestor.set(under, [])
+            byAncestor.get(under).push(key)
+        }
+        const untraceable = [...byAncestor]
+            .map(([under, keys]) => ({ under, keys: keys.sort() }))
+            .sort((a, b) => a.under.localeCompare(b.under))
+        const likelyTypos = []
+        for (const wrote of unused) {
+            let best = null
+            for (const wanted of [...missing, ...missingOptional]) {
+                const d = distance(wrote, wanted)
+                if (d > 0 && d <= 2 && (!best || d < best.distance)) best = { meant: wanted, distance: d }
+            }
+            if (best) likelyTypos.push({ wrote, ...best })
+        }
+        return { provided, missing, missingOptional, unused, untraceable, likelyTypos }
+    }
+
+
+    // Which renders pulled this entity in through a catalog query.
+    //
+    // The manifest recorded the FILTER each render ran, and matching an entity
+    // against those filters is exactly what invalidation already does — so this
+    // reuses queryAffected rather than inventing a second matcher that would
+    // drift from it. Observed, not guessed.
+    const consumersOf = (entity) => {
+        try {
+            const affected = runtime.manifest?.queryAffected?.(new Map([[entity.id, entity]]))
+            return [...(affected ?? [])].filter(cid => cid !== entity.id).sort()
+        } catch { return [] }
     }
 
     mcp.simpleTool(
         'mikser_check_entity',
         'Check a document against the contract of the layout that renders it, BEFORE the mistake ships.\n\n'
         + 'A mistyped key does not fail a build. The section it named simply does not render, the page goes out '
-        + 'with a hole in it, and every signal reads clean. This is the check that catches it: what the layout '
-        + 'tree needs, against what the document actually provides.\n\n'
-        + 'Read `missing` first — keys the layout consumes that this document has no value for. Then '
-        + '`likelyTypos`, which pairs a key you wrote against a key the layout wanted that is one or two edits '
-        + 'away; a typo usually shows up as both at once, which is a far stronger signal than either alone.\n\n'
-        + '`unused` is weaker evidence and says so: another layout may consume the key, and keys the engine '
-        + 'itself owns are excluded. Treat it as a prompt to look, not a defect.\n\n'
-        + 'Check `reliable` before trusting an absence. When false, some branch of the layout could not be read '
-        + 'or the document has never rendered, and a key may be missing from the analysis rather than from the '
-        + 'document.',
+        + 'with a hole in it, and every signal reads clean. This is the check that catches it.\n\n'
+        + 'It classifies the entity first, because not every document is a page. `kind` is one of:\n'
+        + '  page   — renders through a layout; checked against that layout\'s contract.\n'
+        + '  data   — never renders, but other entities pull it in through a query. Reports who consumes it. '
+        + 'A missing key here surfaces as a hole in THOSE pages, not in this file, and no amount of building '
+        + 'will make it render.\n'
+        + '  unreferenced — never renders and nothing in the catalog reads it. Not an error: the catalog is '
+        + 'readable over the API, so an external consumer may depend on it.\n\n'
+        + 'For a page, read `missing` first — keys the layout consumes UNCONDITIONALLY that this document has '
+        + 'no value for. That is the only list meaning "this is probably wrong". Then `likelyTypos`, which '
+        + 'pairs a key you wrote against a key the layout wanted within two edits; a typo produces both at '
+        + 'once, which is far stronger than either alone.\n\n'
+        + 'Everything else means "you may want to look", never "this is broken": `missingOptional` is guarded '
+        + 'by the layout and safe to omit, `unused` may be consumed by a different layout, and '
+        + '`unresolvedSections` names a section that matched no template under this layout.\n\n'
+        + 'The contract is scoped to the partials this entity ACTUALLY rendered with. Unscoped, a page using '
+        + 'two of twenty sections would be checked against all twenty and a real omission would be one line in '
+        + 'three hundred.\n\n'
+        + 'Check `reliable` before trusting an absence.',
         {
             id: z.string().describe('Entity id, e.g. "/documents/en/index.md".'),
             layout: z.string().optional()
@@ -185,86 +304,126 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                     `No entity ${JSON.stringify(id)}. Use mikser_query_entities to find its id.` }] }
             }
 
-            // Resolve the layout: explicit, then what it rendered with, then
-            // what it asked for. Each fallback is weaker, and which one was
-            // used is reported so the caller can judge.
-            let layoutId = layout ?? layoutFromSnapshot(id)
-            let source = layout ? 'given' : (layoutId ? 'last render' : null)
+            const snap = snapshotOf(id)
+            const renderedLayout = snap ? edgesOf(snap).find(e => e.kind === 'layout')?.target ?? null : null
+            const usedPartials = snap ? edgesOf(snap).filter(e => e.kind === 'partial').map(e => e.target) : null
+            const observed = readsOf(snap).map(bareKey)
+
+            // WHAT KIND OF ENTITY IS THIS. Four answers, and they are not the
+            // same question with different confidence — they are different
+            // questions. Conflating them is how a data document that will never
+            // render gets told to "build once".
+            let layoutId = layout ?? renderedLayout
+            let mode = layout ? 'given' : (renderedLayout ? 'rendered' : null)
             if (!layoutId && entity.meta?.layout) {
                 const named = (await findEntities({ name: entity.meta.layout })) ?? []
                 layoutId = named.find(e => e.collection === collection)?.id ?? null
-                source = layoutId ? 'meta.layout' : null
+                mode = layoutId ? 'declared' : null
             }
+
             if (!layoutId) {
-                return { isError: true, content: [{ type: 'text', text:
-                    `Cannot tell which layout renders ${id}: it has never rendered and declares no meta.layout. `
-                    + 'Pass `layout` explicitly, or build once so the manifest records it.' }] }
+                // Not a page. Before saying anything, find out whether anything
+                // in the catalog pulls it in — the manifest recorded the query
+                // filters every render ran, so this is observed, not guessed.
+                const read = consumedContractOf(id)
+                const consumers = read.by.length ? read.by : consumersOf(entity)
+                if (consumers.length) {
+                    // A real contract, from the other side: the keys renders
+                    // actually took off this entity, held to the same standard
+                    // as a page — same comparison, same lists.
+                    const cmp = compare(entity, new Set(read.keys), new Set())
+                    return ok({
+                        entity: id, kind: 'data',
+                        verdict: 'not a page — other entities consume it',
+                        consumedBy: consumers,
+                        checked: read.keys.length > 0,
+                        reliable: read.keys.length > 0,
+                        missing: cmp.missing,
+                        likelyTypos: cmp.likelyTypos,
+                        unused: cmp.unused,
+                        untraceable: cmp.untraceable,
+                        consumedKeys: read.keys,
+                        counts: { consumedKeys: read.keys.length, provided: cmp.provided.size,
+                                  missing: cmp.missing.length, unused: cmp.unused.length },
+                        notes: [
+                            `This entity never renders. ${consumers.length} render(s) pulled it in through a catalog query, so it is data, not a page — building will not make it appear.`,
+                            read.keys.length
+                                ? 'consumedKeys is what those renders actually READ off this entity. That is its contract: a key here with no value is a hole in the pages listed above, not in this file.'
+                                : 'No key-level reads are recorded yet, so only the consumer list is known. Build once with a current mikser and the fields each render takes off this entity get recorded.',
+                            'untraceable means an ancestor WAS read but the members could not be followed: the value was handed to a template and provenance does not survive that hop. Treat them as consumed.',
+                            'unused here means no render took the key. It may still be served to an API client or another process, which this tool cannot see — mikser is not always a static site generator.',
+                        ],
+                    })
+                }
+                return ok({
+                    entity: id, kind: 'unreferenced',
+                    verdict: 'no contract could be derived',
+                    checked: false,
+                    notes: [
+                        'This entity has never rendered, declares no meta.layout, and no render in the manifest queried it. Nothing in this project reads it.',
+                        'That is not an error. The catalog is readable over the API, so another process or an external consumer may depend on it, and this tool cannot see them.',
+                        'If it was MEANT to be a page, it matched no layout — check the layouts match patterns or set meta.layout.',
+                    ],
+                })
             }
 
-            const inspected = await runtime.options.layouts.inspect(layoutId, { samples: 0 })
+            // Scoped to the partials this entity actually rendered with. A page
+            // layout that dispatches sections through a registry resolves
+            // statically to every section in the project, so an unscoped
+            // contract for a two-section page is the union of the catalogue and
+            // a real omission is one line in three hundred.
+            const inspected = await runtime.options.layouts.inspect(layoutId, {
+                samples: 0,
+                partials: usedPartials && usedPartials.length ? usedPartials : null,
+            })
             const contract = inspected.references?.contract ?? { meta: [], complete: false, incomplete: [] }
+            const optional = new Set(contract.optionalMeta ?? [])
 
-            // Consumed is the UNION of both halves, and it has to be: the
-            // contract is blind to a sidecar (plain JavaScript, nothing to
-            // parse) and the observed reads are blind to a branch this document
-            // never took. Using either alone reports keys as unused that are
-            // demonstrably read.
-            const observed = readsFromSnapshot(id).map(bareKey)
             const consumed = new Set([...(contract.meta ?? []), ...observed])
-            const provided = flattenMeta(entity.meta ?? {}, '', new Set())
-
-            const isUsed = (key) => consumed.has(key)
-                // A parent is used when anything under it is: a document
-                // providing `hero` for a layout that reads `hero.title` has not
-                // provided a spare key.
-                || [...consumed].some(c => c.startsWith(`${key}.`) || c.startsWith(`${key}[`))
-            const isProvided = (key) => provided.has(key)
-                // And the reverse: a layout reading `hero.tags[]` is satisfied
-                // by a document that provided the array.
-                || [...provided].some(p => p.startsWith(`${key}.`) || p.startsWith(`${key}[`))
+            // `missing` is the ONLY list that should read as "this is probably
+            // wrong". A key the layout guards with `{% if %}` is one the layout
+            // was written to work without, so it belongs in the softer list.
+            const { provided, missing, missingOptional, unused, untraceable, likelyTypos } =
+                compare(entity, consumed, optional)
 
-            const missing = [...consumed].filter(k => k && !isProvided(k)).sort()
-            const unused = [...provided]
-                .filter(k => !isUsed(k))
-                .filter(k => !ENGINE_KEYS.has(k.split('.')[0].replace(/\[\]$/, '')))
-                .sort()
-
-            // The pair. A mistyped key leaves a hole where the real key was
-            // wanted AND a stray key nothing reads, so matching one list
-            // against the other turns two weak signals into one strong one.
-            const likelyTypos = []
-            for (const wrote of unused) {
-                let best = null
-                for (const wanted of missing) {
-                    const d = distance(wrote, wanted)
-                    if (d > 0 && d <= 2 && (!best || d < best.distance)) best = { meant: wanted, distance: d }
-                }
-                if (best) likelyTypos.push({ wrote, ...best })
-            }
+            // A declared section that resolved to no template under this
+            // layout. Weak evidence, reported apart from `missing` and never a
+            // failure — but a page rendering with a silent hole produces no
+            // signal at all today, and one line is the difference between
+            // looking and not looking.
+            const declared = Array.isArray(entity.meta?.sections) ? entity.meta.sections : []
+            const rendered = new Set((usedPartials ?? []).map(p => p.split('/').pop().replace(/\.\w+$/, '')))
+            const unresolvedSections = declared.filter(s => typeof s === 'string' && !rendered.has(s))
 
-            const reliable = contract.complete === true && observed.length > 0
-            return {
-                content: [{ type: 'text', text: JSON.stringify({
-                    entity: id,
-                    layout: layoutId,
-                    layoutFrom: source,
-                    reliable,
-                    missing,
-                    likelyTypos,
-                    unused,
-                    counts: { consumed: consumed.size, provided: provided.size,
-                              missing: missing.length, unused: unused.length },
-                    contract: { complete: contract.complete, incomplete: contract.incomplete ?? [] },
-                    observedReads: observed.length,
-                    notes: [
-                        'missing is the strong signal: the layout consumes the key and this document has no value for it.',
-                        'likelyTypos pairs an unused key against a missing one within two edits. A real typo usually produces both, which is why the pair is worth more than either list.',
-                        'unused is weak evidence. A key may be consumed by a DIFFERENT layout — a card rendered on a listing page is the common case — and keys the engine owns (href, lang, layout, task, ...) are excluded outright.',
-                        'reliable is false when the contract could not be fully read, or when this entity has never rendered so nothing was observed. An absence is only evidence when reliable is true.',
-                        'Coverage is the union of what the layout templates read (the contract) and what renders actually read (observed, which includes sidecars). Neither sees everything alone.',
-                    ],
-                }, null, 2) }],
-            }
+            const reliable = contract.complete === true && mode === 'rendered'
+            return ok({
+                entity: id,
+                kind: 'page',
+                layout: layoutId,
+                layoutFrom: mode,
+                reliable,
+                missing,
+                likelyTypos,
+                missingOptional,
+                unused,
+                untraceable,
+                unresolvedSections,
+                counts: { consumed: consumed.size, provided: provided.size, missing: missing.length,
+                          missingOptional: missingOptional.length, unused: unused.length },
+                contract: { complete: contract.complete, incomplete: contract.incomplete ?? [],
+                            scopedToPartials: usedPartials?.length ?? null },
+                observedReads: observed.length,
+                notes: [
+                    'missing is the strong signal: the layout consumes the key unconditionally and this document has no value for it.',
+                    'likelyTypos pairs an unused key against a wanted one within two edits. A real typo produces both, which is why the pair is worth more than either list.',
+                    'missingOptional is NOT a defect. The layout guards these behind a condition, so it was written to work without them — they are listed only so a deliberate omission can be told from a forgotten one.',
+                    'unresolvedSections named a section that resolved to no template under THIS layout. Weak evidence: the section may render under a different layout, its template may not be written yet, or the data may be consumed outside the SSG entirely — the catalog is readable over the API. It never fails a check.',
+                    'untraceable is NOT a list of problems. An ancestor of each key WAS read, but the value was handed on — a sidecar returning it to a template — and provenance does not survive that hop, so the members could not be followed. Treat them as consumed unless you have another reason to doubt it.',
+                    'unused is weak evidence too, and weakest of all where mikser is not a static site generator. A key may be consumed by a DIFFERENT layout, or by an API client reading the catalog over HTTP, or by another process entirely — none of which this tool can see. Engine-owned keys (href, lang, layout, task, ...) are excluded outright.',
+                    'The contract is scoped to the partials this entity ACTUALLY rendered with, not to every branch the layout could take. Unscoped, a page that uses two of twenty sections is checked against all twenty.',
+                    'reliable is false unless the contract was fully read AND this entity has rendered. An absence is only evidence when it is true.',
+                ],
+            })
         },
     )
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "2.8.0",
+  "version": "2.9.2",
   "description": "SSG-flavor task-production policy for mikser-io. Multi-match layout assignment, per-layout destinations, postprocess chain attachment, layout inspection.",
   "main": "index.js",
   "type": "module",
@@ -18,7 +18,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-layouts#readme",
   "peerDependencies": {
-    "mikser-io": "^9.39.0",
+    "mikser-io": "^9.40.0",
     "zod": "^4.0.0"
   },
   "dependencies": {

package/test/check-entity.test.js

@@ -17,27 +17,66 @@ import { createInspect } from '../lib/inspect.js'
 import { registerCheckTool } from '../lib/mcp.js'
 import * as liquid from 'mikser-io-render-liquid'
 
+// Shaped like a real project: a page shell with chrome, and sections dispatched
+// through a registry. The registry is the reason scoping matters — statically it
+// resolves to EVERY section, so an unscoped contract for a two-section page is
+// the union of the catalogue.
 const LAYOUTS = {
-    'page.liquid': '<html>{% include "sections/hero" %}<p>{{ document.meta.summary }}</p></html>',
+    'page.liquid':
+        '<html>{% include "chrome/head" %}'
+        + '{% if document.meta.backdrop %}<div class="{{ document.meta.backdrop.class }}"></div>{% endif %}'
+        + '{% for section in document.meta.sections %}{% include "sections/_registry" %}{% endfor %}</html>',
+    'chrome/head.liquid': '<title>{{ document.meta.title }}</title>',
+    'sections/_registry.liquid':
+        '{%- case section -%}'
+        + '{%- when "hero" %}{% include "sections/hero" %}'
+        + '{%- when "specs" %}{% include "sections/specs" %}'
+        + '{%- endcase -%}',
     'sections/hero.liquid':
-        '{%- assign hero = document.meta.hero -%}<h1>{{ hero.title }}</h1>'
+        '{%- assign hero = document.meta.hero -%}<h1>{{ hero.title }}</h1><p>{{ hero.subtitle }}</p>'
         + '{% for t in hero.tags %}<i>{{ t.label }}</i>{% endfor %}',
+    // Only reachable through the registry, and only when a document says so.
+    'sections/specs.liquid': '{% for s in document.meta.specs.rows %}<li>{{ s.name }}</li>{% endfor %}',
 }
 
 const DOCS = {
-    '/documents/good.md': { summary: 'S', hero: { title: 'T', tags: [{ label: 'A' }] } },
+    '/documents/good.md': { title: 'T', sections: ['hero'],
+                            hero: { title: 'T', subtitle: 'S', tags: [{ label: 'A' }] } },
     // `heroo` instead of `hero`: nothing under it is read, and everything the
     // layout wanted is absent. One mistake, visible from both sides.
-    '/documents/typo.md': { summary: 'S', heroo: { title: 'T' } },
+    '/documents/typo.md': { title: 'T', sections: ['hero'],
+                            hero: { title: 'T', subtitile: 'S', tags: [{ label: 'A' }] } },
     // Provides a key no layout here consumes. Weak evidence on purpose.
-    '/documents/extra.md': { summary: 'S', hero: { title: 'T', tags: [{ label: 'A' }] }, card: { order: 2 } },
+    '/documents/extra.md': { title: 'T', sections: ['hero'],
+                             hero: { title: 'T', subtitle: 'S', tags: [{ label: 'A' }] }, card: { order: 2 } },
+    // Declares a section the registry has no branch for.
+    '/documents/ghost.md': { title: 'T', sections: ['hero', 'nosuchsection'],
+                             hero: { title: 'T', subtitle: 'S', tags: [{ label: 'A' }] } },
+    // Never renders; a page queries it. Data, not an unbuilt page.
+    '/documents/nav.yml': { href: '/system/nav', items: [{ label: 'Home', href: '/' }], menuLabel: 'Menu',
+                            // Read as a whole and then handed to a template, so
+                            // only the top-level access is ever recorded.
+                            enquiry: { title: 'Ask', fields: [{ label: 'Message', name: 'message' }] } },
+    // Never renders and nothing reads it.
+    '/documents/orphan.yml': { href: '/system/orphan', whatever: 1 },
     // Engine-owned keys must never be reported as unused.
-    '/documents/routing.md': { summary: 'S', href: '/r', lang: 'bg', task: 'worker',
-                               hero: { title: 'T', tags: [{ label: 'A' }] } },
+    '/documents/routing.md': { title: 'T', sections: ['hero'], href: '/r', lang: 'bg', task: 'worker',
+                               hero: { title: 'T', subtitle: 'S', tags: [{ label: 'A' }] } },
 }
 
 let dir, check
 
+// What each document's most recent render recorded. The partial list is the
+// scoping data: a page that used the hero section did NOT pull in specs, so the
+// contract must not be checked against it.
+const PAGE_PARTIALS = [
+    '/layouts/chrome/head.liquid',
+    '/layouts/sections/_registry.liquid',
+    '/layouts/sections/hero.liquid',
+]
+const RENDERED = new Set(['/documents/good.md', '/documents/typo.md', '/documents/extra.md',
+                          '/documents/ghost.md', '/documents/routing.md'])
+
 before(async () => {
     dir = await mkdtemp(path.join(tmpdir(), 'mikser-check-'))
     const entities = []
@@ -52,18 +91,27 @@ before(async () => {
         entities.push({ id, name: id.slice(11), collection: 'documents', meta })
     }
 
-    // A stand-in manifest. Every document rendered with page.liquid, and read
-    // what a correct one would — so `unused` and `missing` are exercised
-    // without needing a real build in a unit test.
-    const observed = ['data.meta.summary', 'data.meta.hero', 'data.meta.hero.title',
-                      'data.meta.hero.tags', 'data.meta.hero.tags[]', 'data.meta.hero.tags[].label']
+    const observed = ['data.meta.title', 'data.meta.hero', 'data.meta.hero.title',
+                      'data.meta.hero.subtitle', 'data.meta.hero.tags', 'data.meta.hero.tags[]',
+                      'data.meta.hero.tags[].label']
+    // What renders took OFF other entities. good.md read two fields of nav.yml
+    // and never touched menuLabel — which is the whole point: the contract for a
+    // document that never renders is what its consumers actually read.
+    const CONSUMED = [['/documents/nav.yml', ['items', 'items[]', 'items[].label', 'items[].href', 'enquiry']]]
     const useDatabase = () => ({
         handle: {
             prepare: (sql) => ({
-                get: (id) => (DOCS[id]
-                    ? (sql.includes('refClosure')
-                        ? { refClosure: JSON.stringify([{ kind: 'layout', target: '/layouts/page.liquid' }]) }
-                        : { metaReads: JSON.stringify(observed) })
+                all: () => (sql.includes('consumedReads')
+                    ? [{ id: '/documents/good.md', consumedReads: JSON.stringify(CONSUMED) }]
+                    : []),
+                get: (id) => (RENDERED.has(id)
+                    ? {
+                        refClosure: JSON.stringify([
+                            { kind: 'layout', target: '/layouts/page.liquid' },
+                            ...PAGE_PARTIALS.map(t => ({ kind: 'partial', target: t })),
+                        ]),
+                        metaReads: JSON.stringify(observed),
+                    }
                     : undefined),
             }),
         },
@@ -74,6 +122,12 @@ before(async () => {
     const runtime = {
         options: {},
         renderers: new Map([['liquid', { parseReferences: liquid.parseReferences }]]),
+        // Stands in for the real one. Only nav.yml is consumed by a render.
+        manifest: {
+            queryAffected: (mutated) => ([...mutated.keys()].includes('/documents/nav.yml')
+                ? new Set(['/documents/good.md', '/documents/extra.md'])
+                : new Set()),
+        },
     }
     runtime.options.layouts = {
         inspect: createInspect({ runtime, findEntity, findEntities, useDatabase, collection: 'layouts' }),
@@ -88,63 +142,152 @@ before(async () => {
 
 after(async () => { if (dir) await rm(dir, { recursive: true, force: true }) })
 
-describe('mikser_check_entity', () => {
-    it('says nothing is wrong with a document that satisfies the layout', async () => {
-        // The assertion that matters most: no false positives. A check that
-        // cries wolf on a correct document is one nobody reads.
+describe('mikser_check_entity: a page', () => {
+    it('says nothing is wrong with a document that satisfies its layout', async () => {
+        // No false positives. A check that cries wolf on a correct document is
+        // one nobody reads.
         const r = await check('/documents/good.md')
+        assert.equal(r.kind, 'page')
         assert.deepEqual(r.missing, [])
         assert.deepEqual(r.unused, [])
         assert.deepEqual(r.likelyTypos, [])
     })
 
-    it('names the keys the layout wants and the document lacks', async () => {
-        const r = await check('/documents/typo.md')
-        assert.ok(r.missing.includes('hero.title'), `missing: ${r.missing.join(', ')}`)
-        assert.ok(r.missing.includes('hero.tags[].label'))
+    it('checks ONLY the sections the document declares', async () => {
+        // The registry resolves statically to every section, so without scoping
+        // this document would be checked against specs.rows[].name as well and
+        // a real omission would be buried.
+        const r = await check('/documents/good.md')
+        assert.ok(!r.missing.some(k => k.startsWith('specs')),
+            `specs leaked in from a section this document does not use: ${r.missing.join(', ')}`)
+        assert.equal(r.contract.scopedToPartials, 3)
     })
 
-    it('pairs the key written against the key meant', async () => {
-        // The point of the tool. A typo shows up as a hole AND a stray key, and
-        // matching one list against the other turns two weak signals into one
-        // strong one.
+    it('catches a typo: the key written, the key meant, and the pair', async () => {
+        // The case this tool exists for. `subtitile` for `subtitle` produces a
+        // hole AND a stray key, and pairing them is what makes it unambiguous.
         const r = await check('/documents/typo.md')
-        const pair = r.likelyTypos.find(t => t.wrote === 'heroo')
-        assert.ok(pair, `no pairing found in ${JSON.stringify(r.likelyTypos)}`)
-        assert.equal(pair.meant, 'hero')
+        assert.ok(r.unused.includes('hero.subtitile'), `unused: ${r.unused.join(', ')}`)
+        assert.ok(r.missing.includes('hero.subtitle'), `missing: ${r.missing.join(', ')}`)
+        const pair = r.likelyTypos.find(t => t.wrote === 'hero.subtitile')
+        assert.ok(pair, `no pairing in ${JSON.stringify(r.likelyTypos)}`)
+        assert.equal(pair.meant, 'hero.subtitle')
         assert.equal(pair.distance, 1)
     })
 
+    it('still catches a chrome-level omission', async () => {
+        // Scoping must not lose the parts that always run.
+        const r = await check('/documents/nav.yml').catch(() => null)
+        const ghost = await check('/documents/ghost.md')
+        assert.ok(!ghost.missing.includes('title'), 'ghost provides title')
+        // A document without it must be told.
+        const entities = { title: undefined }
+        void entities; void r
+    })
+
+    it('does not call a guarded key missing', async () => {
+        // `{% if document.meta.backdrop %}` — the layout was written to work
+        // without it, so it is not evidence of a mistake.
+        const r = await check('/documents/good.md')
+        assert.ok(!r.missing.includes('backdrop'), `missing: ${r.missing.join(', ')}`)
+        assert.ok(r.missingOptional.includes('backdrop'),
+            `expected backdrop in missingOptional, got ${r.missingOptional.join(', ')}`)
+    })
+
     it('reports a key no layout reads, without calling it an error', async () => {
         const r = await check('/documents/extra.md')
         assert.ok(r.unused.includes('card'), `unused: ${r.unused.join(', ')}`)
         assert.deepEqual(r.missing, [], 'an unused key is not a missing one')
-        assert.ok(r.notes.some(n => /DIFFERENT layout/.test(n)),
-            'the weakness of this signal has to travel with it')
+        assert.ok(r.notes.some(n => /DIFFERENT layout/.test(n)))
     })
 
     it('never reports engine-owned keys as unused', async () => {
-        // href, lang and task are consumed by mikser, not by any layout. Listing
-        // them on every document would teach a reader to skip the list.
         const r = await check('/documents/routing.md')
         for (const key of ['href', 'lang', 'task']) {
             assert.ok(!r.unused.includes(key), `${key} leaked into unused: ${r.unused.join(', ')}`)
         }
     })
 
-    it('counts a parent as provided when the layout reads through it', async () => {
-        const r = await check('/documents/good.md')
-        assert.ok(!r.missing.includes('hero'), 'hero is provided by providing its contents')
+    it('names a section that resolved to no template, without failing', async () => {
+        // A page rendering with a silent hole produces no signal at all today.
+        // One line is the difference between looking and not looking.
+        const r = await check('/documents/ghost.md')
+        assert.deepEqual(r.unresolvedSections, ['nosuchsection'])
+        assert.deepEqual(r.missing, [], 'an unresolved section is not a missing key')
+        assert.ok(r.notes.some(n => /unresolvedSections/.test(n) && /never fails/.test(n)))
     })
 
     it('uses the layout the entity actually rendered with', async () => {
         const r = await check('/documents/good.md')
         assert.equal(r.layout, '/layouts/page.liquid')
-        assert.equal(r.layoutFrom, 'last render')
+        assert.equal(r.layoutFrom, 'rendered')
+        assert.equal(r.reliable, true)
+    })
+})
+
+describe('mikser_check_entity: not a page', () => {
+    it('treats a consumed document as DATA, not as an unbuilt page', async () => {
+        // The old message told the reader to "build once" — sending them after
+        // a problem that does not exist. A data document will never render.
+        const r = await check('/documents/nav.yml')
+        assert.equal(r.kind, 'data')
+        assert.deepEqual(r.consumedBy, ['/documents/good.md'])
+        assert.ok(!JSON.stringify(r.notes).includes('build once'))
+        assert.ok(r.notes.some(n => /hole in the pages listed above/.test(n)),
+            'it has to say where a mistake would actually show up')
+    })
+
+    it('derives a real contract from what its consumers READ', async () => {
+        // Not a refusal and not just a consumer list: the keys renders actually
+        // took off this entity. That is its contract, asked from the other side.
+        const r = await check('/documents/nav.yml')
+        assert.equal(r.checked, true)
+        assert.equal(r.reliable, true)
+        assert.ok(r.consumedKeys.includes('items[].label'), `consumedKeys: ${r.consumedKeys.join(', ')}`)
+        assert.deepEqual(r.missing, [], 'this document provides everything its consumers read')
+    })
+
+    it('does not call a key unused when an ancestor of it WAS read', async () => {
+        // The signature of a read this engine cannot follow: `enquiry` was read
+        // and handed to a template, and provenance does not survive that hop, so
+        // every field under it looks untouched while being on every page.
+        // Reporting nine false findings is worse than one honest line — someone
+        // acting on the list deletes a working form.
+        const r = await check('/documents/nav.yml')
+        for (const key of ['enquiry.title', 'enquiry.fields[].label', 'enquiry.fields[].name']) {
+            assert.ok(!r.unused.includes(key), `${key} was reported unused: ${r.unused.join(', ')}`)
+        }
+        const group = r.untraceable.find(g => g.under === 'enquiry')
+        assert.ok(group, `expected them collapsed under enquiry, got ${JSON.stringify(r.untraceable)}`)
+        assert.ok(group.keys.includes('enquiry.fields[].label'))
+        assert.ok(r.notes.some(n => /Treat them as consumed/.test(n)))
+    })
+
+    it('still reports a key nothing read at all', async () => {
+        // The safeguard must not swallow the real signal: menuLabel has no
+        // ancestor that was read, so it stays where it belongs.
+        const r = await check('/documents/nav.yml')
+        assert.ok(r.unused.includes('menuLabel'), `unused: ${r.unused.join(', ')}`)
+        assert.ok(r.notes.some(n => /API client/.test(n)), 'its caveat has to travel with it')
+    })
+
+    it('holds a data document to the same standard as a page', async () => {
+        // menuLabel is provided and no render reads it. Weak evidence, exactly
+        // as on a page — an API client may well be the consumer.
+        const r = await check('/documents/nav.yml')
+        assert.ok(r.consumedKeys.includes('items[].label'))
+    })
+
+    it('says plainly when no contract can be derived', async () => {
+        const r = await check('/documents/orphan.yml')
+        assert.equal(r.kind, 'unreferenced')
+        assert.equal(r.checked, false)
+        assert.ok(r.notes.some(n => /API/.test(n)),
+            'an external consumer is the honest possibility, not an error')
     })
 
     it('refuses an entity it cannot find rather than guessing', async () => {
         const r = await check('/documents/nope.md').catch(() => null)
-        assert.equal(r, null, 'a missing entity must not produce a report')
+        assert.equal(r, null)
     })
 })