mikser-io-layouts 2.6.1 → 2.8.0

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

@@ -23,6 +23,7 @@ import _ from 'lodash'
 import {
     inputHashOf,
     createTrack,
+    recordReads,
     queryContext,
     useDatabase,
 } from 'mikser-io'
@@ -248,7 +249,13 @@ export function createOnBeforeRender({
                 // invalidations when a newly-added entity should make the
                 // listing change. partial slot disabled — sidecars don't
                 // load partials themselves.
-                const sidecarTrack = createTrack({ partial: false })
+                // `meta: true` records which of the entity's own meta keys
+                // the sidecar reads. This is the half of a layout's contract
+                // that static parsing structurally cannot reach: a sidecar is
+                // 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 })
                 if (existsSync(sidecarPath)) {
                     try {
                         // Stamp = the shared sidecar digest, so the URL
@@ -270,9 +277,21 @@ export function createOnBeforeRender({
                     }
                     if (load) {
                         try {
+                            // The sidecar sees a read-recording view of the
+                            // entity. Only `meta` is wrapped — id, name and uri
+                            // are plumbing, and recording them as content keys
+                            // would bury the ones that matter.
+                            //
+                            // Prefixed `meta.` rather than `data.meta.`: these
+                            // are the DOCUMENT's own keys, read before any
+                            // transform the sidecar applies, while the template
+                            // reads whatever the sidecar hands back.
+                            const observed = entity?.meta
+                                ? { ...entity, meta: recordReads(entity.meta, 'meta', sidecarTrack.metaRead) }
+                                : entity
                             data = await queryContext.run(
                                 { entityId: entity.id, track: sidecarTrack },
-                                () => load({ entity, findEntity, findEntities, runtime, signal }),
+                                () => load({ entity: observed, findEntity, findEntities, runtime, signal }),
                             )
                         } catch (err) {
                             logger.error('Layout sidecar %s load() threw: %s', sidecarPath.replace(runtime.options.workingFolder + '/', ''), err.message)
@@ -361,7 +380,8 @@ export function createOnBeforeRender({
                                 postprocessor: entity.layout.postprocessor,
                                 postprocessors: entity.layout.postprocessors ?? (entity.layout.postprocessor ? [entity.layout.postprocessor] : []),
                                 tasks: entity.meta?.task || TASKS.INLINE,
-                            }, { data, plugins, sidecarQueries: sidecarTrack.queries })
+                            }, { data, plugins, sidecarQueries: sidecarTrack.queries,
+                                 sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])] })
                         }
                     }
                 } else {
@@ -388,7 +408,8 @@ export function createOnBeforeRender({
                         // when matching entities are added/modified/
                         // deleted. The paginated branch above already
                         // does this.
-                        { data, plugins, sidecarQueries: sidecarTrack.queries })
+                        { data, plugins, sidecarQueries: sidecarTrack.queries,
+                          sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])] })
                     }
                 }
             } // end per-layout for-loop

package/lib/inspect.js

@@ -65,6 +65,10 @@ export function createInspect({ runtime, findEntity, findEntities, useDatabase,
             sampleEntities, useDatabase, layoutName: layout.name,
         })
 
+        const contract = await buildContract({
+            layout, templateSource, runtime, findEntities, collection,
+        })
+
         return {
             layout: {
                 id:            layout.id,
@@ -78,6 +82,7 @@ export function createInspect({ runtime, findEntity, findEntities, useDatabase,
             references: {
                 runtime: runtimeRefs,
                 static:  staticRefs,
+                contract,
             },
             samples: sampleEntities,
         }
@@ -98,7 +103,7 @@ async function collectRuntimeRefs({ sampleEntities, useDatabase, layoutName }) {
     }
 
     const stmt = db.handle.prepare(`
-        SELECT destination, refClosure, renderedAt, inputHash, outputHash
+        SELECT destination, refClosure, metaReads, renderedAt, inputHash, outputHash
         FROM mikser_snapshots
         WHERE id = ?
         ORDER BY renderedAt DESC
@@ -106,6 +111,11 @@ async function collectRuntimeRefs({ sampleEntities, useDatabase, layoutName }) {
     `)
 
     const perSample = []
+    // Union across samples. One document exercises one set of branches, so the
+    // keys a layout needs are only visible across several of them — which is
+    // also why this can never be a complete answer on its own, and why the
+    // static closure sits beside it.
+    const observed = new Set()
     for (const sample of sampleEntities) {
         const row = stmt.get(sample.id)
         if (!row) {
@@ -116,6 +126,11 @@ async function collectRuntimeRefs({ sampleEntities, useDatabase, layoutName }) {
         try {
             refClosure = row.refClosure ? JSON.parse(row.refClosure) : []
         } catch { /* malformed JSON: surface empty rather than throw */ }
+        let metaReads = []
+        try {
+            metaReads = row.metaReads ? JSON.parse(row.metaReads) : []
+        } catch { /* same: an unreadable column is not worth throwing over */ }
+        for (const path of metaReads) observed.add(path)
         perSample.push({
             entityId:   sample.id,
             destination: row.destination,
@@ -123,6 +138,7 @@ async function collectRuntimeRefs({ sampleEntities, useDatabase, layoutName }) {
             inputHash:  row.inputHash,
             outputHash: row.outputHash,
             refClosure,
+            metaReads,
         })
     }
 
@@ -130,7 +146,18 @@ async function collectRuntimeRefs({ sampleEntities, useDatabase, layoutName }) {
     if (!everRendered) {
         return { available: false, reason: `No sample entity using "${layoutName}" has rendered yet` }
     }
-    return { available: true, samples: perSample }
+    return {
+        available: true,
+        samples: perSample,
+        // Meta keys these renders ACTUALLY read, union of the samples.
+        //
+        // The counterpart to references.contract, and deliberately not merged
+        // with it: the contract says what the templates COULD read, this says
+        // what was read. Only this one sees a sidecar, because a sidecar is
+        // plain JavaScript; only the contract sees a branch no sample took.
+        // Reported apart so a caller can tell which of the two it is trusting.
+        metaReads: [...observed].sort(),
+    }
 }
 
 // Wrap the renderer's parser so a thrown error in one engine doesn't
@@ -148,3 +175,173 @@ function safeParseReferences(renderer, source, templateName) {
         return { available: false, reason: `Renderer "${templateName}" parseReferences() threw: ${err.message}` }
     }
 }
+
+// The contract of a layout AND everything it pulls in.
+//
+// `references.static` answers "what does this FILE mention", which is one file
+// deep and in that file's own vocabulary. Neither is what an author needs. A
+// page layout is mostly `{% include %}`, so its own file mentions almost
+// nothing; and a section that opens `{% assign hero = data.meta.hero %}` then
+// talks about `hero.tags`, which names nothing the author can write.
+//
+// So this walks the whole tree and rewrites every path back into the caller's
+// terms. `hero.tags` inside sections/hero.liquid, reached through
+// `{% render 'ui/tags', tags: hero.tags %}`, comes back out as
+// `data.meta.hero.tags` — which IS the key in the document's front matter.
+//
+// Engine-agnostic by construction: it never looks at template syntax, only at
+// what each renderer's own parseReferences() reports. An engine that exposes no
+// parser contributes nothing and SAYS SO, in `incomplete`. A partial-looking
+// contract reported as complete would be worse than no contract at all, which
+// is the whole reason the caps below are reported rather than silently applied.
+const MAX_DEPTH = 12
+const MAX_TEMPLATES = 200
+
+async function buildContract({ layout, templateSource, runtime, findEntities, collection }) {
+    const consumes  = new Set()
+    const templates = []
+    const incomplete = []
+    const visited   = new Set()
+
+    // A path rewritten through the substitutions in scope. Only the FIRST
+    // segment can be an alias — `hero.tags` where `hero` is bound to
+    // `data.meta.hero` is `data.meta.hero.tags`; the tail is property access on
+    // whatever that resolved to and never needs rewriting.
+    const resolve = (path, subs) => {
+        if (!path) return path
+        const [head, ...rest] = String(path).split('.')
+        // The head may carry the element marker a parser adds for a loop
+        // variable: `{% for t in tags %}{{ t.label }}` reports `tags[].label`.
+        // The binding is keyed by the plain name, so the marker comes off for
+        // the lookup and goes back on after it — otherwise every key read off
+        // a loop item stops dead at the partial boundary, which is precisely
+        // the hop this exists to cross.
+        const isElement = head.endsWith('[]')
+        const base = subs[isElement ? head.slice(0, -2) : head]
+        if (!base) return path
+        return [isElement ? `${base}[]` : base, ...rest].join('.')
+    }
+
+    const layoutNamed = async (name) => {
+        const rows = (await findEntities({ name })) ?? []
+        return rows.find(e => e.collection === collection) ?? null
+    }
+
+    async function walk(name, template, source, bindings, depth) {
+        // Keyed by name AND bindings: one partial rendered with two different
+        // arguments has two different contracts, and collapsing them would
+        // lose one. Cyclic includes and runaway fan-out are bounded instead.
+        const key = `${name}|${JSON.stringify(bindings)}`
+        if (visited.has(key)) return
+        if (depth > MAX_DEPTH) {
+            incomplete.push({ template: name, reason: `include depth exceeded ${MAX_DEPTH}` })
+            return
+        }
+        if (visited.size >= MAX_TEMPLATES) {
+            incomplete.push({ template: name, reason: `stopped after ${MAX_TEMPLATES} templates` })
+            return
+        }
+        visited.add(key)
+
+        const renderer = runtime.renderers?.get(template)
+        if (typeof renderer?.parseReferences !== 'function') {
+            incomplete.push({
+                template: name,
+                reason: renderer
+                    ? `renderer "${template}" exposes no parseReferences(), so nothing under it was read`
+                    : `no renderer registered for template "${template}"`,
+            })
+            return
+        }
+        const parsed = safeParseReferences(renderer, source, template)
+        if (!parsed.available || parsed.parseError) {
+            incomplete.push({ template: name, reason: parsed.reason ?? `parse error: ${parsed.parseError}` })
+            return
+        }
+
+        // Substitutions in scope: what this template was called with, then its
+        // own assigns layered on top — an assign can refer to an argument, so
+        // it is resolved against what is known so far.
+        const subs = { ...bindings }
+        for (const a of parsed.assigns ?? []) {
+            if (a?.key && a.from) subs[a.key] = resolve(a.from, subs)
+        }
+
+        const resolved = []
+        for (const v of parsed.variables ?? []) {
+            const r = resolve(v, subs)
+            consumes.add(r)
+            resolved.push(r)
+        }
+        templates.push({ template: name, bindings, consumes: resolved.sort() })
+
+        for (const p of parsed.partials ?? []) {
+            // Engines that have not been taught to report arguments still
+            // report NAMES, so the tree is still walked — just without the
+            // bindings that make aliases resolvable.
+            const isRich = p && typeof p === 'object'
+            const partialName = isRich ? p.name : p
+            if (!partialName) continue
+
+            const childBindings = {}
+            if (isRich) {
+                for (const [arg, path] of Object.entries(p.args ?? {})) {
+                    childBindings[arg] = resolve(path, subs)
+                }
+                for (const alias of p.aliases ?? []) {
+                    if (alias?.to && alias.from) childBindings[alias.to] = resolve(alias.from, subs)
+                }
+            } else {
+                incomplete.push({
+                    template: partialName,
+                    reason: `renderer "${template}" reports partial names but not their arguments, `
+                        + 'so anything reached through an argument is unresolved',
+                })
+            }
+
+            const entity = await layoutNamed(partialName)
+            if (!entity) {
+                incomplete.push({ template: partialName, reason: 'no layout entity has this name' })
+                continue
+            }
+            let childSource
+            try {
+                childSource = await readFile(entity.uri, 'utf8')
+            } catch (err) {
+                incomplete.push({ template: partialName, reason: `unreadable (${entity.uri}): ${err.message}` })
+                continue
+            }
+            await walk(partialName, entity.template, childSource, childBindings, depth + 1)
+        }
+    }
+
+    await walk(layout.name, layout.template, templateSource, {}, 0)
+
+    // 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 meta = [...consumes]
+        .map(p => (META_ROOT.test(p) ? p.replace(META_ROOT, '') : (p.startsWith('meta.') ? p.slice(5) : null)))
+        .filter(Boolean)
+
+    return {
+        available: true,
+        // 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(),
+        consumes: [...consumes].sort(),
+        templates,
+        incomplete,
+    }
+}

package/lib/matching.js

@@ -22,7 +22,7 @@ import path from 'node:path'
 
 import _ from 'lodash'
 import { primaryDestination } from './destination.js'
-import { reportWarning, isFullCycle } from 'mikser-io'
+import { isFullCycle } from 'mikser-io'
 
 export function createOnProcessed({
     runtime, useLogger, useJournal,
@@ -69,11 +69,9 @@ export function createOnProcessed({
             // So 'post' does NOT match a document named 'post'; '@/post' and
             // '/documents/post.md' both do.
             const onName = pattern.startsWith('@/')
-            reportWarning('layout-pattern-no-match', {
-                pattern, layout: options.match[pattern], evaluated: matchTally.evaluated,
-                matchedAgainst: onName ? 'name' : 'id',
-            })
             logger.warn(
+                { code: 'layout-pattern-no-match', pattern, layout: options.match[pattern],
+                  evaluated: matchTally.evaluated, matchedAgainst: onName ? 'name' : 'id' },
                 'Layout pattern %j (→ %j) matched none of the %d entities evaluated. ' +
                 'It is matched against entity.%s%s.',
                 pattern, options.match[pattern], matchTally.evaluated,

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
@@ -19,7 +19,19 @@ export function registerMcpTools({ runtime, useLogger }) {
 
     mcp.simpleTool(
         'mikser_layouts_inspect',
-        'Inspect a layout: template source, references (runtime: precise refClosure from recent renders via the manifest; static: variables / partials / iterations / helpers parsed from source by the renderer plugin), and sample entities currently targeting it. Use this to answer "what does this layout need from an entity" before drafting a preview render — saves a guess-and-render-empty cycle.',
+        'Inspect a layout and everything it pulls in. Answers "what does this layout need from a document" '
+        + 'before you write one — which saves a guess-and-render-empty cycle, and is the only way to catch a '
+        + 'mistyped key before it ships a page with a section silently missing.\n\n'
+        + 'START WITH references.contract.meta. It is the list of document meta keys the WHOLE layout tree '
+        + 'consumes, resolved through includes and renamings into the vocabulary a document actually writes — '
+        + 'so `data.meta.hero.tags` in a partial three files down comes back as `hero.tags`. Compare it against '
+        + 'the meta you are about to write: a key in the contract with no value is a gap, and a key you wrote '
+        + 'that appears nowhere in it is usually a typo.\n\n'
+        + 'Check references.contract.complete before trusting a comparison. When false, some branch could not be '
+        + 'read and references.contract.incomplete names each one with a reason.\n\n'
+        + 'Also returns the template source, sample entities targeting the layout, and both reference views: '
+        + 'runtime (what recent renders actually touched) and static (what the source mentions, including '
+        + 'branches no render has taken).',
         {
             id: z.string().describe('Layout id, e.g. "/layouts/reports/royalty.html-pdf.liquid". Use mikser_query_entities with { collection: "layouts" } to discover ids.'),
             samples: z.number().int().min(0).max(10).optional().describe('How many existing entities currently using this layout to include as data-shape examples. Default 3. Only entities with explicit meta.layout match; auto-matched layouts are not surfaced.'),
@@ -33,8 +45,12 @@ export function registerMcpTools({ runtime, useLogger }) {
                         text: JSON.stringify({
                             ...result,
                             notes: [
+                                'references.contract is the one to read first: the whole layout tree walked, with partial arguments and renamings resolved, so `meta` lists document keys in the form a document writes them. `[]` marks an element — `hero.tags[].label` means each tag has a label, not that the list does.',
+                                'references.contract.complete is false when any branch could not be read, and `incomplete` names each with a reason. An incomplete contract is still useful, but a key missing from it may only be missing because that branch was unreadable — do not treat absence as proof.',
+                                'references.contract covers TEMPLATES. A layout sidecar is plain JavaScript and cannot be parsed, so a key only it reads will not appear there — look in references.runtime.metaReads instead.',
+                                'references.runtime.metaReads is what renders actually READ, sidecars included, unioned across the samples. It sees a sidecar the contract cannot; it does not see a branch no sample took. The two are complements, not alternatives.',
                                 'references.runtime is the precise answer from manifest snapshots — what the renderer actually touched in recent renders. Empty if the layout has never rendered.',
-                                'references.static is the renderer-plugin AST walk of the template source — what the source mentions, including unexercised conditional branches. Empty when the renderer does not expose parseReferences (markdown / metatext / custom).',
+                                'references.static is the renderer-plugin walk of THIS FILE only, in this file\'s own vocabulary. references.contract is the same walk followed across every partial and resolved into the author\'s. Prefer the contract.',
                                 'samples only includes entities with explicit meta.layout. Auto-matched layouts are not listed; use mikser_query_entities with a filename-pattern filter for those.',
                             ],
                         }, null, 2),
@@ -50,5 +66,207 @@ 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
+
+    // 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 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 }
+    }
+
+    const readsFromSnapshot = (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 [] }
+    }
+
+    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.',
+        {
+            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.` }] }
+            }
+
+            // 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)
+            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
+            }
+            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.' }] }
+            }
+
+            const inspected = await runtime.options.layouts.inspect(layoutId, { samples: 0 })
+            const contract = inspected.references?.contract ?? { meta: [], complete: false, incomplete: [] }
+
+            // 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}[`))
+
+            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 })
+            }
+
+            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) }],
+            }
+        },
+    )
+
+    logger.debug('MCP tool registered: mikser_check_entity (layouts plugin)')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "2.6.1",
+  "version": "2.8.0",
   "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.25.0",
+    "mikser-io": "^9.39.0",
     "zod": "^4.0.0"
   },
   "dependencies": {

package/test/check-entity.test.js

@@ -0,0 +1,150 @@
+// 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'
+
+const LAYOUTS = {
+    'page.liquid': '<html>{% include "sections/hero" %}<p>{{ document.meta.summary }}</p></html>',
+    'sections/hero.liquid':
+        '{%- assign hero = document.meta.hero -%}<h1>{{ hero.title }}</h1>'
+        + '{% for t in hero.tags %}<i>{{ t.label }}</i>{% endfor %}',
+}
+
+const DOCS = {
+    '/documents/good.md': { summary: 'S', hero: { title: 'T', 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' } },
+    // 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 } },
+    // 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' }] } },
+}
+
+let dir, check
+
+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 })
+    }
+
+    // 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 useDatabase = () => ({
+        handle: {
+            prepare: (sql) => ({
+                get: (id) => (DOCS[id]
+                    ? (sql.includes('refClosure')
+                        ? { refClosure: JSON.stringify([{ kind: 'layout', target: '/layouts/page.liquid' }]) }
+                        : { 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 }]]),
+    }
+    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', () => {
+    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.
+        const r = await check('/documents/good.md')
+        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('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.
+        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.equal(pair.distance, 1)
+    })
+
+    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')
+    })
+
+    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('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')
+    })
+
+    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')
+    })
+})

package/test/contract.test.js

@@ -0,0 +1,185 @@
+// The contract of a layout AND everything it pulls in.
+//
+// `references.static` reports what ONE FILE mentions, in that file's own
+// vocabulary. For a real page layout that is close to useless: page.liquid is
+// mostly `{% include %}` and mentions almost nothing itself, while the section
+// that does the work opens `{% assign hero = data.meta.hero %}` and then talks
+// about `hero.tags` — a name that appears in no document and that an author
+// cannot write.
+//
+// So an agent checking a document against a layout had nothing to check
+// against, which is how a typo'd key ships a page with a section missing.
+//
+// These pin the two hops that used to break the chain: a value passed AS AN
+// ARGUMENT to a partial, and a value renamed by an alias. Both have to come
+// back out in the author's terms — `data.meta.*` — or the contract cannot be
+// diffed against a document's front matter.
+
+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 * as liquid from 'mikser-io-render-liquid'
+
+// page → sections/hero → ui/tags. The key under test, `hero.tags`, is reached
+// through an alias in the middle file and an argument into the last one, so
+// nothing but a resolved closure can find it.
+const FILES = {
+    'page.liquid':
+        '<html><body>{% include "chrome/nav" %}'
+        + '{% for section in data.meta.sections %}{% include "sections/hero" %}{% endfor %}'
+        + '</body></html>',
+    'chrome/nav.liquid': '<nav>{{ data.meta.title }}</nav>',
+    'sections/hero.liquid':
+        '{%- assign hero = data.meta.hero -%}'
+        + '<h1>{{ hero.title }}</h1>'
+        + '{% if hero.background %}<img src="{{ hero.background }}">{% endif %}'
+        + '{% render "ui/tags", tags: hero.tags, heading: hero.tagsTitle %}',
+    'ui/tags.liquid':
+        '<ul>{% for t in tags %}<li>{{ t.label }}<span>{{ t.icon }}</span></li>{% endfor %}</ul>',
+}
+
+let dir, inspect, contract
+
+before(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), 'mikser-contract-'))
+    const entities = []
+    for (const [rel, content] of Object.entries(FILES)) {
+        const uri = path.join(dir, rel)
+        await mkdir(path.dirname(uri), { recursive: true })
+        await writeFile(uri, content)
+        const name = rel.replace(/\.liquid$/, '')
+        entities.push({ id: `/layouts/${rel}`, name, uri, collection: 'layouts', template: 'liquid', format: 'html' })
+    }
+
+    // The real liquid parser, dispatched exactly the way render does it — by
+    // `entity.template`. Nothing here knows what liquid syntax looks like.
+    const runtime = { renderers: new Map([['liquid', { parseReferences: liquid.parseReferences }]]) }
+
+    inspect = createInspect({
+        runtime,
+        findEntity:   async ({ id }) => entities.find(e => e.id === id) ?? null,
+        findEntities: async (q) => entities.filter(e => q.name == null || e.name === q.name),
+        useDatabase:  () => null,
+        collection:   'layouts',
+    })
+    contract = (await inspect('/layouts/page.liquid', { samples: 0 })).references.contract
+})
+
+after(async () => { if (dir) await rm(dir, { recursive: true, force: true }) })
+
+describe('the layout contract', () => {
+    it('follows a key through an ARGUMENT into the partial that consumes it', () => {
+        // `{% render "ui/tags", tags: hero.tags %}` — dropping the argument was
+        // the hole: ui/tags talks about `tags`, and nothing tied that back to
+        // the document key it was handed.
+        assert.ok(contract.meta.includes('hero.tags'),
+            `expected hero.tags in the contract, got: ${contract.meta.join(', ')}`)
+    })
+
+    it('resolves an alias back into the vocabulary the author writes', () => {
+        // sections/hero says `hero.title`. No document has a `hero.title` at
+        // the root — it is `data.meta.hero.title`, and only the assign says so.
+        assert.ok(contract.meta.includes('hero.title'))
+        assert.ok(contract.meta.includes('hero.background'))
+        assert.ok(!contract.consumes.some(c => c === 'hero.title'),
+            'the unresolved local name must not survive into the contract')
+    })
+
+    it('reaches keys two hops down, through an argument AND a loop', () => {
+        // ui/tags iterates what it was handed and reads `.label` off each item.
+        // Two rewrites away from the document: tags → hero.tags → an element.
+        assert.ok(contract.meta.includes('hero.tags[].label'),
+            `expected hero.tags[].label, got: ${contract.meta.join(', ')}`)
+        assert.ok(contract.meta.includes('hero.tags[].icon'))
+    })
+
+    it('marks an element as an element, not as the collection', () => {
+        // `hero.tags.label` would be a key that exists on no document — the
+        // label is on each tag, not on the list.
+        assert.ok(!contract.meta.includes('hero.tags.label'))
+    })
+
+    it('includes what the layout itself consumes, not only its partials', () => {
+        assert.ok(contract.meta.includes('sections'))
+        assert.ok(contract.meta.includes('title'), 'chrome/nav is walked too')
+    })
+
+    it('reports itself COMPLETE when every branch was read', () => {
+        assert.equal(contract.complete, true,
+            `unexpected gaps: ${JSON.stringify(contract.incomplete)}`)
+        assert.deepEqual(contract.incomplete, [])
+    })
+
+    it('names every template it walked, so the closure is auditable', () => {
+        const walked = contract.templates.map(t => t.template).sort()
+        assert.deepEqual(walked, ['chrome/nav', 'page', 'sections/hero', 'ui/tags'])
+    })
+})
+
+// A contract that LOOKS complete but silently skipped a branch is worse than
+// no contract: it invites an agent to trust a set difference that is missing
+// half its right-hand side. So every gap has to be named, and `complete` has
+// to go false the moment one exists.
+describe('the layout contract, where it cannot see', () => {
+    const build = async (files, rendererFor) => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'mikser-contract-gap-'))
+        const entities = []
+        for (const [rel, content] of Object.entries(files)) {
+            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(/\.\w+$/, ''), uri,
+                collection: 'layouts', template: rel.endsWith('.liquid') ? 'liquid' : 'mystery',
+                format: 'html',
+            })
+        }
+        const inspect = createInspect({
+            runtime: { renderers: rendererFor },
+            findEntity:   async ({ id }) => entities.find(e => e.id === id) ?? null,
+            findEntities: async (q) => entities.filter(e => q.name == null || e.name === q.name),
+            useDatabase:  () => null,
+            collection:   'layouts',
+        })
+        const out = (await inspect('/layouts/page.liquid', { samples: 0 })).references.contract
+        await rm(dir, { recursive: true, force: true })
+        return out
+    }
+
+    const liquidOnly = new Map([['liquid', { parseReferences: liquid.parseReferences }]])
+
+    it('says so when an included partial does not exist', async () => {
+        const c = await build({ 'page.liquid': '{% include "sections/absent" %}' }, liquidOnly)
+        assert.equal(c.complete, false)
+        assert.ok(c.incomplete.some(i => i.template === 'sections/absent'),
+            `expected the missing partial to be named, got ${JSON.stringify(c.incomplete)}`)
+    })
+
+    it('says so when a partial is rendered by an engine that cannot be parsed', async () => {
+        // markdown and metatext are real cases: they render content, and have
+        // no parseReferences to expose. The closure must degrade loudly.
+        const c = await build({
+            'page.liquid': '{% include "sections/opaque" %}',
+            'sections/opaque.mystery': 'whatever this engine does',
+        }, new Map([
+            ['liquid', { parseReferences: liquid.parseReferences }],
+            ['mystery', { /* a renderer with no parser */ }],
+        ]))
+        assert.equal(c.complete, false)
+        const gap = c.incomplete.find(i => i.template === 'sections/opaque')
+        assert.ok(gap, `expected the opaque partial to be named, got ${JSON.stringify(c.incomplete)}`)
+        assert.match(gap.reason, /parseReferences/)
+    })
+
+    it('still reports everything it COULD read, rather than giving up', async () => {
+        const c = await build({
+            'page.liquid': '{{ data.meta.title }}{% include "sections/absent" %}',
+        }, liquidOnly)
+        assert.equal(c.complete, false)
+        assert.ok(c.meta.includes('title'), 'a gap in one branch must not discard the others')
+    })
+})

package/test/unit.test.js

@@ -158,9 +158,15 @@ describe('layouts plugin', () => {
             const warnings = h.logs.filter(l =>
                 l.level === 'warn' && l.args.join(' ').includes('Layout pattern'))
             assert.equal(warnings.length, 1, `expected one warning, got ${warnings.length}`)
-            // The harness records (format, ...args) unformatted, so render it
-            // the way the logger would before asserting on the message.
-            const text = format(...warnings[0].args)
+            // Structured first, sentence second — the call is
+            // logger.warn({ code, ... }, msg, ...values), and the fields are
+            // what the build report keys on. The harness records the args
+            // unformatted, so render the message the way the logger would.
+            const [fields, ...message] = warnings[0].args
+            assert.equal(fields.code, 'layout-pattern-no-match', 'carries the code the report is asserted on')
+            assert.equal(fields.pattern, 'nonesuch/*')
+            assert.equal(fields.matchedAgainst, 'id')
+            const text = format(...message)
             assert.match(text, /nonesuch/, 'names the pattern that matched nothing')
             assert.ok(!text.includes("'post'"), 'must not name the pattern that DID match')
             assert.match(text, /matched against entity\.id/, 'names the field this pattern is matched against')