mikser-io-layouts 2.7.0 → 2.9.1

package/index.js

@@ -102,7 +102,7 @@ export function layouts(userOptions = {}) {
         // in the plugins array for this to fire; that constraint is
         // documented in mikser-io's CLAUDE.md.
         onLoaded(async () => {
-            registerMcpTools({ runtime, useLogger })
+            registerMcpTools({ runtime, useLogger, findEntity, findEntities, useDatabase, collection })
         })
 
         onSync(collection, async ({ action, context }) => {

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,8 @@ 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 ?? [])] })
+                                 sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])],
+                                 sidecarConsumedReads: [...(sidecarTrack.consumedReads ?? [])].map(([k, v]) => [k, [...v]]) })
                         }
                     }
                 } else {
@@ -409,7 +427,8 @@ export function createOnBeforeRender({
                         // deleted. The paginated branch above already
                         // does this.
                         { data, plugins, sidecarQueries: sidecarTrack.queries,
-                          sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])] })
+                          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')
@@ -320,18 +351,34 @@ async function buildContract({ layout, templateSource, runtime, findEntities, co
     // The subset an author actually writes. Everything else in `consumes` is
     // render-time furniture — helpers, loop variables, plugin surfaces — and
     // is kept, but it is not what a document's front matter is checked against.
+    // Entity meta, whichever root binding reached it.
+    //
+    // A template can arrive at the same keys by more than one name: `data` is
+    // whatever a layout sidecar returned, and the entity is ALSO bound under
+    // its own type, so `document.meta.title` and `data.meta.title` are the same
+    // document key. Matching only `data.` was lmed-shaped — a project with no
+    // 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]
-        .filter(p => p.startsWith('data.meta.'))
-        .map(p => p.slice('data.meta.'.length))
+        .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

@@ -10,7 +10,7 @@
 
 import { z } from 'zod'
 
-export function registerMcpTools({ runtime, useLogger }) {
+export function registerMcpTools({ runtime, useLogger, findEntity, findEntities, useDatabase, collection }) {
     const mcp = runtime.options.mcp
     if (!mcp) return   // mcp plugin not loaded — nothing to register
     if (!runtime.options.layouts?.inspect) return   // shouldn't happen if we run after our own inspect setup, but defensive
@@ -66,5 +66,317 @@ export function registerMcpTools({ runtime, useLogger }) {
         },
     )
 
+    registerCheckTool({ runtime, findEntity, findEntities, useDatabase, collection, logger })
+
     logger.debug('MCP tool registered: mikser_layouts_inspect (layouts plugin)')
 }
+
+// Meta keys the ENGINE owns. They appear on documents, are consumed by mikser
+// itself rather than by any layout, and would otherwise be reported as unused on
+// every entity — noise that teaches a reader to ignore the list.
+const ENGINE_KEYS = new Set([
+    'layout', 'layouts', 'task', 'destination', 'format', 'template', 'href',
+    'lang', 'url', 'pages', 'parent', 'plugins', 'presets', 'refs', 'date',
+    'draft', 'stamp', 'postprocessor',
+])
+
+// A document's meta in the same vocabulary a layout contract uses: dotted
+// paths, with `[]` for "each element of" rather than an index. Both sides have
+// to speak it or the comparison is meaningless.
+function flattenMeta(value, prefix, out) {
+    if (value === null || typeof value !== 'object') return out
+    if (Array.isArray(value)) {
+        // One `[]` for the whole array: the contract says "each tag has a
+        // label", never "tag 7 has a label", so element shapes are merged.
+        if (value.length) out.add(`${prefix}[]`)
+        for (const item of value) flattenMeta(item, `${prefix}[]`, out)
+        return out
+    }
+    for (const [k, v] of Object.entries(value)) {
+        const path = prefix ? `${prefix}.${k}` : k
+        out.add(path)
+        flattenMeta(v, path, out)
+    }
+    return out
+}
+
+// Observed reads carry the prefix of where they were seen — `meta.` for the
+// document's own keys as a sidecar read them, `data.meta.` for what a template
+// read. Both describe the same document, so both reduce to the bare key.
+const bareKey = (p) => p.replace(/^[A-Za-z_$][\w$]*\.meta\./, '').replace(/^meta\./, '')
+
+// Edit distance, capped: only used to ask "did they mean this one", so anything
+// past a couple of edits is not a typo and the answer stops mattering.
+function distance(a, b) {
+    if (Math.abs(a.length - b.length) > 3) return 99
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+    for (let i = 1; i <= a.length; i++) {
+        let last = prev[0]
+        prev[0] = i
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = prev[j]
+            prev[j] = Math.min(
+                prev[j] + 1,
+                prev[j - 1] + 1,
+                last + (a[i - 1] === b[j - 1] ? 0 : 1),
+            )
+            last = tmp
+        }
+    }
+    return prev[b.length]
+}
+
+export function registerCheckTool({ runtime, findEntity, findEntities, useDatabase, collection, logger }) {
+    const mcp = runtime.options.mcp
+
+    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
+        try {
+            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, [])
+
+    // 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 { 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 unused = [...provided]
+            .filter(k => !isUsed(k))
+            .filter(k => !ENGINE_KEYS.has(k.split('.')[0].replace(/\[\]$/, '')))
+            .sort()
+        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, 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.\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()
+                .describe('Layout id to check against. Omit to use the layout this entity last rendered with, '
+                    + 'which is what the manifest recorded rather than a prediction.'),
+        },
+        async ({ id, layout }) => {
+            const entity = await findEntity({ id })
+            if (!entity) {
+                return { isError: true, content: [{ type: 'text', text:
+                    `No entity ${JSON.stringify(id)}. Use mikser_query_entities to find its id.` }] }
+            }
+
+            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
+                mode = layoutId ? 'declared' : null
+            }
+
+            if (!layoutId) {
+                // 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,
+                        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.',
+                            '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.',
+                    ],
+                })
+            }
+
+            // 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 ?? [])
+
+            const consumed = new Set([...(contract.meta ?? []), ...observed])
+            // `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, likelyTypos } =
+                compare(entity, consumed, optional)
+
+            // 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 && mode === 'rendered'
+            return ok({
+                entity: id,
+                kind: 'page',
+                layout: layoutId,
+                layoutFrom: mode,
+                reliable,
+                missing,
+                likelyTypos,
+                missingOptional,
+                unused,
+                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.',
+                    '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.',
+                ],
+            })
+        },
+    )
+
+    logger.debug('MCP tool registered: mikser_check_entity (layouts plugin)')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "2.7.0",
+  "version": "2.9.1",
   "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

@@ -0,0 +1,267 @@
+// Checking a document against the contract of the layout that renders it.
+//
+// A mistyped key does not fail a build. The section it named simply does not
+// render, the page ships with a hole, and every signal reads clean. This is the
+// check that catches it before it ships, and it exists because the two halves it
+// needs — the layout contract and what renders actually read — are useless
+// separately: the contract is blind to a sidecar, and observed reads are blind
+// to a branch this document never took.
+
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+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 "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><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': { 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': { 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': { 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' },
+    // 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': { 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 = []
+    for (const [rel, content] of Object.entries(LAYOUTS)) {
+        const uri = path.join(dir, rel)
+        await mkdir(path.dirname(uri), { recursive: true })
+        await writeFile(uri, content)
+        entities.push({ id: `/layouts/${rel}`, name: rel.replace(/\.liquid$/, ''), uri,
+                        collection: 'layouts', template: 'liquid' })
+    }
+    for (const [id, meta] of Object.entries(DOCS)) {
+        entities.push({ id, name: id.slice(11), collection: 'documents', meta })
+    }
+
+    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']]]
+    const useDatabase = () => ({
+        handle: {
+            prepare: (sql) => ({
+                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),
+            }),
+        },
+    })
+
+    const findEntity   = async ({ id }) => entities.find(e => e.id === id) ?? null
+    const findEntities = async (q) => entities.filter(e => q.name == null || e.name === q.name)
+    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' }),
+    }
+    const registry = new Map()
+    runtime.options.mcp = { simpleTool: (name, _d, _s, handler) => registry.set(name, handler) }
+    registerCheckTool({ runtime, findEntity, findEntities, useDatabase,
+                        collection: 'layouts', logger: { debug() {} } })
+
+    check = async (id) => JSON.parse((await registry.get('mikser_check_entity')({ id })).content[0].text)
+})
+
+after(async () => { if (dir) await rm(dir, { recursive: true, force: true }) })
+
+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('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('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')
+        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)))
+    })
+
+    it('never reports engine-owned keys as unused', async () => {
+        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('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, '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('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.unused.includes('menuLabel'), `unused: ${r.unused.join(', ')}`)
+        assert.ok(r.notes.some(n => /API client/.test(n)))
+    })
+
+    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)
+    })
+})