mikser-io-layouts 2.9.3 → 2.11.0

package/README.md

@@ -176,7 +176,28 @@ See the [mikser-io rendering docs](https://github.com/almero-digital-marketing/m
 
 ## `inspect()` primitive
 
-`runtime.options.layouts.inspect(layoutId, { samples })` runs a layout against `samples` real entities and returns the resolved template source, render context, parsed refs, and any errors. Used by the `mikser-io-mcp` plugin's `mikser_layouts_inspect` MCP tool but available to any plugin that wants to surface layout introspection.
+`runtime.options.layouts.inspect(layoutId, { samples, partials })` returns a layout's template source, sample entities, and three views of what it depends on:
+
+- **`references.contract`** — the whole layout tree walked, with partial arguments and renamings resolved, so `meta` lists document keys in the form a document writes them. Pass `partials` (the ids a render actually used, from the manifest) to scope it to one page: a layout that dispatches sections through a registry otherwise resolves statically to *every* section in the project.
+- **`references.runtime`** — what recent renders actually touched, including `metaReads`, which sees a layout sidecar that no parser can.
+- **`references.static`** — the single-file parse, in that file's own vocabulary.
+
+`contract.complete` is false when a branch could not be read, and `incomplete` names each with a reason. An incomplete contract is still useful, but absence is not proof.
+
+## Checking a document — `mikser_check_entity`
+
+Answers "does this document have what its layout needs", before the mistake ships. A mistyped key does not fail a build: the section it named simply does not render.
+
+It classifies the entity first, because not every document is a page — `page`, `data` (never renders, but other entities query it; reports who, and what they read off it) or `unreferenced` (nothing in the catalog reads it, which is not an error — the catalog is readable over the API).
+
+Read `missing` first, but check **`missingFrom`**:
+
+- `schema` — a [zod schema](https://www.npmjs.com/package/mikser-io-schemas) declares the key required. Authoritative, and it needed no template parsing.
+- `inferred` — read out of the templates. Strong evidence, not proof: it models one engine's semantics and a guard it cannot see makes a fine document look broken.
+
+With a schema you also get `drift`: `readButNotDeclared` (layouts consume a key nothing declares — a schema gap, or a template typo) and `declaredButNotRead` (declared, unread — dead, or served over the API).
+
+Everything else means "you may want to look", never "this is broken": `missingOptional` is guarded and safe to omit, `unused` may be consumed by another layout or an API client, `untraceable` means an ancestor was read but its members could not be followed, and `unresolvedSections` names a section that matched no template.
 
 ## Entity properties
 

package/lib/mcp.js

@@ -77,7 +77,7 @@ export function registerMcpTools({ runtime, useLogger, findEntity, findEntities,
 const ENGINE_KEYS = new Set([
     'layout', 'layouts', 'task', 'destination', 'format', 'template', 'href',
     'lang', 'url', 'pages', 'parent', 'plugins', 'presets', 'refs', 'date',
-    'draft', 'stamp', 'postprocessor',
+    'draft', 'stamp', 'postprocessor', 'schema',
 ])
 
 // A document's meta in the same vocabulary a layout contract uses: dotted
@@ -153,6 +153,118 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
     const edgesOf = (snap) => parse(snap?.refClosure, [])
     const readsOf = (snap) => parse(snap?.metaReads, [])
 
+    // A DECLARED contract, walked out of a zod schema.
+    //
+    // This is the only source here that is engine-agnostic by construction. It
+    // says nothing about liquid or handlebars, it needs no filter table, and it
+    // states required-versus-optional outright instead of inferring it from
+    // `{% if %}` guards and `| default:` filters — which is the same distinction
+    // reconstructed by reading templates, and got wrong twice.
+    //
+    // Where a schema exists it therefore OUTRANKS anything read out of a
+    // template, and the inferred contract is demoted to reporting drift.
+    const zdef = (t) => t?._zod?.def ?? t?._def ?? {}
+    function schemaKeys(type, prefix, required, optional, depth = 0) {
+        const def = zdef(type)
+        if (!def.type || depth > 12) return
+        switch (def.type) {
+            // A wrapper says the value beneath it may be absent; everything
+            // under it inherits that, since a document omitting the parent
+            // cannot be faulted for omitting its members.
+            case 'optional':
+            case 'nullable':
+            case 'default':
+                if (prefix) { required.delete(prefix); optional.add(prefix) }
+                schemaKeys(def.innerType, prefix, required, new Set(), depth + 1)
+                for (const k of collectAll(def.innerType, prefix, depth + 1)) optional.add(k)
+                return
+            case 'object':
+                for (const [key, child] of Object.entries(def.shape ?? {})) {
+                    const path = prefix ? `${prefix}.${key}` : key
+                    const childDef = zdef(child)
+                    const soft = ['optional', 'nullable', 'default'].includes(childDef.type)
+                    ;(soft ? optional : required).add(path)
+                    schemaKeys(child, path, required, optional, depth + 1)
+                }
+                return
+            case 'array':
+                schemaKeys(def.element, `${prefix}[]`, required, optional, depth + 1)
+                return
+            default:
+                return
+        }
+    }
+    // Every path under a type, regardless of requiredness — used to mark a whole
+    // optional subtree optional.
+    function collectAll(type, prefix, depth = 0) {
+        const req = new Set(); const opt = new Set()
+        schemaKeys(type, prefix, req, opt, depth)
+        return [...req, ...opt]
+    }
+
+    // How this record compares with its own kind.
+    //
+    // A layout contract answers "what does this template read". It cannot answer
+    // "is this record complete AS A RECORD" — a catalog entry missing a field
+    // its siblings all carry renders perfectly, reads nothing that is absent,
+    // and passes every other check here. That is among the commonest content
+    // defects and nothing else in this tool can see it.
+    //
+    // Deliberately weak evidence, and reported as such: records differ for good
+    // reasons, and a document is not wrong for lacking what its neighbours have.
+    // It is a prompt to look.
+    //
+    // Needs a real peer group. With one sibling "most of them" means nothing, so
+    // below MIN_PEERS the comparison is not made rather than made badly.
+    const MIN_PEERS = 3
+    const PEER_SHARE = 0.7
+
+    const declaredTypeOf = (entity) => {
+        const key = runtime.options.schemasKey ?? runtime.options.schemaKey ?? 'meta.schema'
+        return key.split('.').reduce((o, k) => o?.[k], entity) ?? entity?.meta?.schema ?? null
+    }
+
+    const peerGapsFor = async (entity) => {
+        const type = declaredTypeOf(entity)
+        if (!type) return null
+        const key = runtime.options.schemasKey ?? runtime.options.schemaKey ?? 'meta.schema'
+        const siblings = ((await findEntities({ [key]: type })) ?? [])
+            .filter(e => e?.id && e.id !== entity.id && e.collection === entity.collection)
+        if (siblings.length < MIN_PEERS) return null
+
+        const counts = new Map()
+        for (const peer of siblings) {
+            for (const k of flattenMeta(peer.meta ?? {}, '', new Set())) {
+                counts.set(k, (counts.get(k) ?? 0) + 1)
+            }
+        }
+        const mine = flattenMeta(entity.meta ?? {}, '', new Set())
+        const threshold = Math.ceil(siblings.length * PEER_SHARE)
+        const gaps = [...counts]
+            .filter(([k, c]) => c >= threshold && !mine.has(k))
+            .filter(([k]) => !ENGINE_KEYS.has(k.split('.')[0].replace(/\[\]$/, '')))
+            // A key whose PARENT this document also lacks is one finding, not
+            // several: report `card`, not `card.order` and `card.wide` under it.
+            .filter(([k]) => { const parent = k.replace(/\.[^.]+$|\[\]$/, ''); return parent === k || mine.has(parent) })
+            .map(([key, count]) => ({ key, siblings: count, of: siblings.length }))
+            .sort((a, b) => b.siblings - a.siblings || a.key.localeCompare(b.key))
+        return { type, peers: siblings.length, gaps }
+    }
+
+    // The schema declared for this entity, if the schemas plugin is loaded and
+    // the entity names one. `schemaKey` is the plugin's own config — commonly
+    // `meta.layout`, so a layout and its schema share a name.
+    const schemaFor = (entity) => {
+        const api = runtime.options.schemas
+        if (!api?.lookup) return null
+        const key = runtime.options.schemasKey ?? runtime.options.schemaKey ?? 'meta.schema'
+        const name = key.split('.').reduce((o, k) => o?.[k], entity)
+            ?? entity?.meta?.schema ?? entity?.meta?.layout
+        if (!name) return null
+        const schema = api.lookup(name)
+        return schema ? { name, schema } : null
+    }
+
     // What every render read OFF this entity, and who read it.
     //
     // The contract for a document that never renders. `metaReads` answers "what
@@ -331,17 +443,40 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                     // 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())
+                    // A declared schema outranks consumer reads here for the
+                    // same reason it does on a page: it says what the record
+                    // must contain, where consumer reads only say what someone
+                    // happened to look at. Without this a data document was the
+                    // one kind that could not benefit from its own schema.
+                    const declared = schemaFor(entity)
+                    let cmp
+                    if (declared) {
+                        const req = new Set(); const opt = new Set()
+                        schemaKeys(declared.schema, '', req, opt)
+                        cmp = compare(entity, new Set([...req, ...opt]), opt)
+                    } else {
+                        cmp = compare(entity, new Set(read.keys), new Set())
+                    }
+                    // Matters most here: a data document is otherwise only
+                    // checked against whatever its consumers happen to read, so
+                    // a field every sibling carries and nobody reads yet is
+                    // invisible.
+                    const peers = await peerGapsFor(entity)
                     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,
+                        missingFrom: declared ? 'schema' : 'consumers',
                         missing: cmp.missing,
+                        missingOptional: cmp.missingOptional,
                         likelyTypos: cmp.likelyTypos,
                         unused: cmp.unused,
                         untraceable: cmp.untraceable,
+                        ...(peers?.gaps.length
+                            ? { peerGaps: peers.gaps, peerGroup: { type: peers.type, peers: peers.peers } }
+                            : {}),
                         consumedKeys: read.keys,
                         counts: { consumedKeys: read.keys.length, provided: cmp.provided.size,
                                   missing: cmp.missing.length, unused: cmp.unused.length },
@@ -351,15 +486,29 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                                 ? 'consumedKeys is what those renders actually READ off this entity. That is its contract: a key here with no value is a hole in the pages listed above, not in this file.'
                                 : 'No key-level reads are recorded yet, so only the consumer list is known. Build once with a current mikser and the fields each render takes off this entity get recorded.',
                             'untraceable means an ancestor WAS read but the members could not be followed: the value was handed to a template and provenance does not survive that hop. Treat them as consumed.',
+                            'missingFrom says where `missing` came from: "schema" is declared and authoritative; "consumers" means it is derived from what renders actually read off this entity, which only covers what someone happened to look at.',
+                            'peerGaps compares this record with the others declaring the same type — keys most of them carry that this one lacks. For a data document this is often the only check with teeth, since everything else here depends on what a consumer happened to read. Weak evidence, never a failure.',
                             '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.',
                         ],
                     })
                 }
+                // Nothing reads it, so nothing can say what it needs — except
+                // its own kind. This is the one check available here, and the
+                // only place in the tool where peer comparison is not merely
+                // corroboration.
+                const orphanPeers = await peerGapsFor(entity)
                 return ok({
                     entity: id, kind: 'unreferenced',
                     verdict: 'no contract could be derived',
                     checked: false,
+                    ...(orphanPeers?.gaps.length
+                        ? { peerGaps: orphanPeers.gaps,
+                            peerGroup: { type: orphanPeers.type, peers: orphanPeers.peers } }
+                        : {}),
                     notes: [
+                        ...(orphanPeers?.gaps.length
+                            ? ['peerGaps is the only check that could be made here: nothing reads this entity, so nothing defines what it needs, but the other records declaring the same type do. Weak evidence, never a failure — records differ for good reasons.']
+                            : []),
                         '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.',
@@ -383,8 +532,42 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
             // `missing` is the ONLY list that should read as "this is probably
             // wrong". A key the layout guards with `{% if %}` is one the layout
             // was written to work without, so it belongs in the softer list.
-            const { provided, missing, missingOptional, unused, untraceable, likelyTypos } =
-                compare(entity, consumed, optional)
+            // `unused` always comes from what is CONSUMED — a key nothing reads
+            // is the question there, and a schema does not answer it.
+            const inferred = compare(entity, consumed, optional)
+            const { provided, unused, untraceable, likelyTypos } = inferred
+
+            // `missing` prefers the DECLARED contract. A schema states
+            // required-versus-optional outright, needs no template parsing, and
+            // is engine-agnostic by construction — where one exists, nothing
+            // read out of a template should be able to call a document broken.
+            const peerCheck = await peerGapsFor(entity)
+            const declaredSchema = schemaFor(entity)
+            let missing = inferred.missing
+            let missingOptional = inferred.missingOptional
+            let drift = null
+            if (declaredSchema) {
+                const req = new Set(); const opt = new Set()
+                schemaKeys(declaredSchema.schema, '', req, opt)
+                // Both sets are candidates: an absent OPTIONAL key still has
+                // to be reported, in the softer list, or a schema's optionality
+                // would silently drop it from the report altogether.
+                const bySchema = compare(entity, new Set([...req, ...opt]), opt)
+                missing = bySchema.missing
+                missingOptional = bySchema.missingOptional
+                // Where the two disagree, which is the drift the schemas plugin
+                // exists to catch: a layout reading a key nobody declared, or a
+                // declared key no layout reads.
+                const knows = (k) => req.has(k) || opt.has(k)
+                    || [...req, ...opt].some(d => d.startsWith(`${k}.`) || d.startsWith(`${k}[`))
+                const isRead = (k) => consumed.has(k)
+                    || [...consumed].some(c => c.startsWith(`${k}.`) || c.startsWith(`${k}[`))
+                drift = {
+                    schema: declaredSchema.name,
+                    readButNotDeclared: [...consumed].filter(k => k && !knows(k)).sort(),
+                    declaredButNotRead: [...req].filter(k => !isRead(k)).sort(),
+                }
+            }
 
             // A declared section that resolved to no template under this
             // layout. Weak evidence, reported apart from `missing` and never a
@@ -402,11 +585,20 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                 layout: layoutId,
                 layoutFrom: mode,
                 reliable,
+                // Where `missing` came from, because the two are not equally
+                // trustworthy and a caller acting on it deserves to know which
+                // it has: 'schema' is declared, 'inferred' is read out of
+                // templates and can be wrong.
+                missingFrom: declaredSchema ? 'schema' : 'inferred',
                 missing,
                 likelyTypos,
                 missingOptional,
+                ...(drift ? { drift } : {}),
                 unused,
                 untraceable,
+                ...(peerCheck?.gaps.length
+                    ? { peerGaps: peerCheck.gaps, peerGroup: { type: peerCheck.type, peers: peerCheck.peers } }
+                    : {}),
                 unresolvedSections,
                 counts: { consumed: consumed.size, provided: provided.size, missing: missing.length,
                           missingOptional: missingOptional.length, unused: unused.length },
@@ -414,9 +606,11 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                             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.',
+                    'missing is the strong signal, but read missingFrom first. "schema" means a zod schema DECLARES the key required — authoritative, and it needed no template parsing. "inferred" means it was read out of the templates, which models one engine\'s semantics and has been wrong: a guard it cannot see makes a fine document look broken. Treat an inferred missing as strong evidence, not proof.',
+                    'drift appears only with a schema, and is where the two sources disagree: readButNotDeclared is a key the layouts consume that nothing declares (a schema gap, or a typo in a template), declaredButNotRead is a declared key no layout reads (dead, or consumed over the API).',
                     '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.',
+                    'peerGaps compares this record with the others declaring the same type: keys most of them carry that this one lacks, with the count as evidence. A layout contract cannot see this — a record missing a field its siblings all have renders perfectly and reads nothing that is absent. Weak evidence, and never a failure: records differ for good reasons.',
                     'unresolvedSections named a section that resolved to no template under THIS layout. Weak evidence: the section may render under a different layout, its template may not be written yet, or the data may be consumed outside the SSG entirely — the catalog is readable over the API. It never fails a check.',
                     'untraceable is NOT a list of problems. An ancestor of each key WAS read, but the value was handed on — a sidecar returning it to a template — and provenance does not survive that hop, so the members could not be followed. Treat them as consumed unless you have another reason to doubt it.',
                     'unused is weak evidence too, and weakest of all where mikser is not a static site generator. A key may be consumed by a DIFFERENT layout, or by an API client reading the catalog over HTTP, or by another process entirely — none of which this tool can see. Engine-owned keys (href, lang, layout, task, ...) are excluded outright.',

package/package.json

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

package/test/check-entity.test.js

@@ -291,3 +291,183 @@ describe('mikser_check_entity: not a page', () => {
         assert.equal(r, null)
     })
 })
+
+// A DECLARED contract outranks one read out of templates.
+//
+// A zod schema says nothing about liquid. It needs no filter table, states
+// required-versus-optional outright rather than inferring it from `{% if %}`
+// guards and `| default:`, and is engine-agnostic by construction. Where one
+// exists, nothing parsed out of a template should be able to call a document
+// broken — that inference has been wrong, and `missing` is the one list that
+// must only ever mean "probably wrong".
+describe('mikser_check_entity: with a declared schema', () => {
+    let checkWithSchema, dir2
+
+    before(async () => {
+        const { z } = await import('zod')
+        dir2 = await mkdtemp(path.join(tmpdir(), 'mikser-check-schema-'))
+        const entities = []
+        for (const [rel, content] of Object.entries(LAYOUTS)) {
+            const uri = path.join(dir2, 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' })
+        }
+        // Declares a key the layouts do NOT read, and omits one they do.
+        const schema = z.object({
+            title: z.string(),
+            byline: z.string(),                    // declared, no layout reads it
+            hero: z.object({
+                title: z.string(),
+                subtitle: z.string().optional(),   // declared optional
+            }),
+        })
+        const doc = { id: '/documents/schemed.md', name: 'schemed', collection: 'documents',
+                      meta: { schema: 'article', title: 'T', sections: ['hero'],
+                              hero: { title: 'T', tags: [{ label: 'A' }] } } }
+        entities.push(doc)
+
+        const useDatabase = () => ({ handle: { prepare: (sql) => ({
+            all: () => [],
+            get: () => (sql.includes('refClosure')
+                ? { refClosure: JSON.stringify([
+                    { kind: 'layout', target: '/layouts/page.liquid' },
+                    ...PAGE_PARTIALS.map(t => ({ kind: 'partial', target: t })),
+                  ]) }
+                : { metaReads: JSON.stringify(['data.meta.title', 'data.meta.hero.title']) }),
+        }) } })
+        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: { schemas: { lookup: (n) => (n === 'article' ? schema : undefined), names: () => ['article'] } },
+            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: (n, _d, _s, h) => registry.set(n, h) }
+        registerCheckTool({ runtime, findEntity, findEntities, useDatabase,
+                            collection: 'layouts', logger: { debug() {} } })
+        checkWithSchema = async (id) =>
+            JSON.parse((await registry.get('mikser_check_entity')({ id })).content[0].text)
+    })
+
+    after(async () => { if (dir2) await rm(dir2, { recursive: true, force: true }) })
+
+    it('takes `missing` from the schema and says so', async () => {
+        const r = await checkWithSchema('/documents/schemed.md')
+        assert.equal(r.missingFrom, 'schema')
+        assert.ok(r.missing.includes('byline'), `missing: ${r.missing.join(', ')}`)
+    })
+
+    it('honours zod optionality instead of inferring it from the template', async () => {
+        // `.optional()` states it. No guard analysis, no filter table.
+        const r = await checkWithSchema('/documents/schemed.md')
+        assert.ok(!r.missing.includes('hero.subtitle'))
+        assert.ok(r.missingOptional.includes('hero.subtitle'),
+            `missingOptional: ${r.missingOptional.join(', ')}`)
+    })
+
+    it('reports drift in both directions', async () => {
+        const r = await checkWithSchema('/documents/schemed.md')
+        assert.equal(r.drift.schema, 'article')
+        // The layouts read hero.tags[].label; nothing declares it.
+        assert.ok(r.drift.readButNotDeclared.some(k => k.startsWith('hero.tags')),
+            `readButNotDeclared: ${r.drift.readButNotDeclared.join(', ')}`)
+        // byline is declared and no layout reads it.
+        assert.ok(r.drift.declaredButNotRead.includes('byline'),
+            `declaredButNotRead: ${r.drift.declaredButNotRead.join(', ')}`)
+    })
+
+    it('labels an inferred contract as inferred when there is no schema', async () => {
+        const r = await check('/documents/good.md')
+        assert.equal(r.missingFrom, 'inferred')
+        assert.ok(r.notes.some(n => /has been wrong/.test(n)),
+            'the weaker source has to say that it is weaker')
+    })
+})
+
+// Is this record complete AS A RECORD?
+//
+// A layout contract cannot answer that. A catalog entry missing a field its
+// siblings all carry renders perfectly, reads nothing that is absent, and passes
+// every other check here — and a derived schema will not catch it either, since
+// a key one sibling lacks becomes `.optional()`. Comparing a record with its own
+// kind is the only thing that sees it.
+//
+// Weak evidence on purpose: records differ for good reasons.
+describe('mikser_check_entity: peer comparison', () => {
+    let peerCheck
+
+    const entry = (n, extra = {}) => ({
+        id: `/documents/cat-${n}.md`, name: `cat-${n}`, collection: 'documents',
+        meta: { schema: 'catalog', title: `T${n}`, href: `/c/${n}`, summary: 'S', ...extra },
+    })
+
+    before(async () => {
+        // Nine complete siblings, one missing `summary`, and one carrying a key
+        // only it has.
+        const entities = [
+            ...Array.from({ length: 9 }, (_, i) => entry(i)),
+            (() => { const e = entry('gap'); delete e.meta.summary; return e })(),
+            entry('extra', { oddball: true }),
+        ]
+        const findEntity = async ({ id }) => entities.find(e => e.id === id) ?? null
+        const findEntities = async (q) => entities.filter(e =>
+            Object.entries(q ?? {}).every(([k, v]) => k.split('.').reduce((o, x) => o?.[x], e) === v))
+        const runtime = { options: {}, renderers: new Map() }
+        runtime.options.layouts = { inspect: async () => ({ references: {} }) }
+        const registry = new Map()
+        runtime.options.mcp = { simpleTool: (n, _d, _s, h) => registry.set(n, h) }
+        registerCheckTool({
+            runtime, findEntity, findEntities,
+            // No snapshots: these never render, so they are data documents.
+            useDatabase: () => ({ handle: { prepare: () => ({ all: () => [], get: () => undefined }) } }),
+            collection: 'layouts', logger: { debug() {} },
+        })
+        peerCheck = async (id) =>
+            JSON.parse((await registry.get('mikser_check_entity')({ id })).content[0].text)
+    })
+
+    it('reports a key most siblings carry and this record lacks', async () => {
+        const r = await peerCheck('/documents/cat-gap.md')
+        const gap = r.peerGaps?.find(g => g.key === 'summary')
+        assert.ok(gap, `no peer gap found: ${JSON.stringify(r.peerGaps)}`)
+        assert.equal(gap.siblings, 10, 'ten of the ten siblings have it')
+        assert.equal(gap.of, 10)
+    })
+
+    it('names the group, so the count means something', async () => {
+        const r = await peerCheck('/documents/cat-gap.md')
+        assert.equal(r.peerGroup.type, 'catalog')
+        assert.equal(r.peerGroup.peers, 10)
+    })
+
+    it('says nothing about a complete record', async () => {
+        // No false positives, or nobody reads the list.
+        const r = await peerCheck('/documents/cat-0.md')
+        assert.equal(r.peerGaps, undefined)
+    })
+
+    it('does not report a key only ONE sibling has', async () => {
+        // `oddball` exists on exactly one record. One record is not a pattern.
+        const r = await peerCheck('/documents/cat-0.md')
+        assert.ok(!(r.peerGaps ?? []).some(g => g.key === 'oddball'))
+    })
+
+    it('never fails the check — it is a prompt, not a defect', async () => {
+        const r = await peerCheck('/documents/cat-gap.md')
+        assert.notEqual(r.kind, undefined)
+        assert.ok(r.notes.some(n => /Weak evidence, never a failure|never a failure/.test(n)),
+            'the weakness has to travel with the finding')
+    })
+
+    it('excludes engine-owned keys from the comparison', async () => {
+        const r = await peerCheck('/documents/cat-gap.md')
+        for (const k of ['schema', 'href', 'lang']) {
+            assert.ok(!(r.peerGaps ?? []).some(g => g.key === k), `${k} leaked into peerGaps`)
+        }
+    })
+})