mikser-io-schemas 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Almero Digital Marketing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,271 @@
+# mikser-io-schemas
+
+Zod-backed entity validation and TypeScript type generation for [mikser-io](https://github.com/almero-digital-marketing/mikser-io).
+
+File-based content is mikser's superpower — but file-based content has no built-in schema. You discover the shape of an entity by reading its `meta` block, and drift between layouts ("did this layout want `publishedAt` or `published`?") accumulates silently until something breaks at render time. This plugin closes that gap *without giving up the file-based model*: schemas are plain `.js` modules next to your config, validation runs as part of the build, and the SDK's `.d.ts` gets regenerated so the frontend gets typed entity access.
+
+## Install
+
+```bash
+npm install --save-dev mikser-io-schemas zod
+```
+
+`mikser-io ^8.2.0` is a peer dependency.
+
+## Quick start
+
+Add the plugin to your config and pick a folder for schemas (default `schemas/`):
+
+```js
+// mikser.config.js
+export default {
+    plugins: ['documents', 'layouts', 'plugin-schemas'],
+
+    schemas: {
+        // schemasFolder: 'schemas',       // default
+        // typesFile:     'entities.d.ts', // default — emitted at the project root
+        // onError:       'warn',          // 'warn' (default) | 'fail' | 'off' (schema-shape only)
+        schemaKey:        'meta.layout',   // REQUIRED for schema-shape validation. No
+                                           // default. Dotted front-matter path that
+                                           // names the schema to match.
+                                           // SSG projects typically pass 'meta.layout';
+                                           // SPA projects (no rendered HTML) pass
+                                           // 'meta.component' since their docs have no
+                                           // layout. When unset, schema-shape validation
+                                           // is off and every loaded schema triggers a
+                                           // finalize warning so the off state is loud.
+                                           //
+                                           // Ref validation (per ADR-0007 A6) runs
+                                           // regardless of schemaKey — every $-keyed
+                                           // field is auto-validated for existence,
+                                           // shape, and collision, as warnings.
+    },
+}
+```
+
+Drop a schema file in `schemas/`:
+
+```js
+// schemas/article.js
+import { z } from 'zod'
+
+export default z.object({
+    title:       z.string().min(1),
+    layout:      z.literal('article'),
+    publishedAt: z.string().datetime(),
+    author:      z.string(),
+    tags:        z.array(z.string()).default([]),
+    hero:        z.string().url().optional(),
+    summary:     z.string().max(280).optional(),
+})
+```
+
+Each entity whose `meta[schemaKey] === 'article'` is now validated. The match is by filename stem — `schemas/article.js` matches docs declaring `article`, `schemas/landing-page.js` matches docs declaring `landing-page`, etc. `schemas.schemaKey` is **required** and has no default — pick the field your project actually uses for dispatch:
+
+- **SSG projects:** `schemaKey: 'meta.layout'` (same field mikser uses for template dispatch)
+- **SPA projects:** `schemaKey: 'meta.component'` (no rendered HTML, no layout)
+
+If a schema file loads but never matches any document during a build, the plugin warns at finalize:
+
+```
+WARN  Schema "article" loaded but never matched any entity — check `schemaKey` (currently 'meta.layout') or verify front-matter declares { layout: 'article' }
+```
+
+If `schemaKey` is unset, every loaded schema generates a louder warning pointing at the missing config:
+
+```
+WARN  Schema "article" loaded but `schemas.schemaKey` is not set — validation is off. Set it to the front-matter path that names the schema, e.g. 'meta.layout' (SSG) or 'meta.component' (SPA).
+```
+
+That makes both failure modes — misconfigured key or no key at all — loud at finalize.
+
+## What validation surfaces
+
+The plugin runs on `onValidate` — mikser's per-entity validation hook. Behaviour depends on `onError`:
+
+| Mode | Behaviour |
+|---|---|
+| `'warn'` *(default)* | Log the validation issue, keep the entity in the catalog, continue the build. Right for adopting schemas on an existing project — broken entries stay visible without breaking deploys. |
+| `'fail'` | Throw on the first invalid entity. The lifecycle marks it as a validation error and the build exits non-zero. Right for greenfield projects or CI. |
+| `'off'` | Validate nothing. Schemas still load and the `.d.ts` is still emitted — useful when you want types without the runtime check. |
+
+Example warning output on a malformed article:
+
+```
+WARN  Validation problem: [CREATE] /content/blog/missing-author.md schema(article) author: Required; publishedAt: Invalid datetime
+```
+
+The error string lists every issue Zod reported. If you want stricter messages or want to fail only on certain fields, use `.refine(...)` inside the schema — every Zod feature works because the schema *is* a Zod object.
+
+## Type generation
+
+After every build, `mikser-io-schemas` regenerates a `.d.ts` describing the union of all schemas. The default location is `entities.d.ts` at the project root; override with `schemas.typesFile`.
+
+```ts
+// entities.d.ts — Generated by mikser-io-schemas. Do not edit by hand.
+
+import type { z } from 'zod'
+import ArticleSchema from './schemas/article.js'
+import ProductSchema from './schemas/product.js'
+
+export type ArticleMeta = z.infer<typeof ArticleSchema>
+export type ProductMeta = z.infer<typeof ProductSchema>
+
+export interface LayoutMap {
+    'article': ArticleMeta
+    'product': ProductMeta
+}
+
+export type LayoutName = keyof LayoutMap
+export type MetaByLayout<L extends LayoutName> = LayoutMap[L]
+```
+
+Consumers — typically a Vue or React app using `mikser-io-sdk-api` — can now type the entities they fetch:
+
+```ts
+import type { MetaByLayout } from '../mikser-content/entities'
+import { useDocument } from 'mikser-io-sdk-vue'
+
+type Article = { meta: MetaByLayout<'article'> }
+
+const { document } = useDocument<Article>('/content/blog/launch')
+// document.value.meta.title   ← string
+// document.value.meta.author  ← string
+// document.value.meta.tags    ← string[]
+```
+
+For a discriminated union over layouts:
+
+```ts
+import type { LayoutMap, LayoutName } from '../mikser-content/entities'
+
+type Entity = {
+    [L in LayoutName]: { layout: L; meta: LayoutMap[L] }
+}[LayoutName]
+```
+
+Now `if (entity.layout === 'article')` narrows `entity.meta` to `ArticleMeta` automatically.
+
+## References between entities
+
+[ADR-0007](https://github.com/almero-digital-marketing/mikser-io/blob/main/documentation/decisions/0007-references-declaration-and-expansion.md) makes references first-class via a tiny naming convention: any meta key starting with `$` is a reference. The value stays a plain string (a leading-slash href, no extension), so `sed`-replace, grep, and YAML/JSON portability are unchanged. What changes is that the engine now *knows* which fields are refs and treats them accordingly — render context normalization strips the `$` so templates see `meta.author` instead of `meta.$author`, the api can `expand` them in a single round-trip, and **this plugin auto-validates that every `$`-keyed value resolves to an actual entity in the catalog**.
+
+```yaml
+---
+layout: article
+title:    Launch
+$author:  /authors/dick           # single ref
+$hero:    /images/launch-hero
+$related:                         # array of refs
+  - /blog/old-post-1
+  - /blog/old-post-2
+seo:
+  $ogImage: /images/og-launch     # nested $-keys also detected
+---
+```
+
+Schema shape for the same article — no special "reference" type, just `z.string()` because that's what's on disk:
+
+```js
+import { z } from 'zod'
+
+export default z.object({
+    layout: z.literal('article'),
+    title:  z.string(),
+    $author:  z.string(),
+    $hero:    z.string().optional(),
+    $related: z.array(z.string()).default([]),
+})
+```
+
+### Deferred, warning-only ref validation
+
+Per ADR-0007 A6, file-based editing is multi-step: an article can be saved before its author file exists, an entity can be renamed leaving N referencing entities temporarily broken, a batch import can land in any order. Any model that errors on broken-ref state at parse time fights normal editing workflows.
+
+This plugin runs ref validation in `onFinalized` (after `onPersist` has populated the catalog) and **emits warnings, never errors**. Four checks run regardless of whether `schemaKey` is set:
+
+- **Shape** — value under a `$`-key isn't a string or string array
+- **Collision** — both `author:` and `$author:` declared in the same entity
+- **Existence** — `$author: /authors/dick` and no entity resolves at that href
+- **Target type** — when typed via `entityRef('author')` (planned), the target's layout doesn't match
+
+Warnings are transition-based: a warning fires the first time an entity's issue set appears or changes; an info fires when an entity that previously had issues comes back clean. Stable repeats are silent so a single broken ref doesn't flood the log every cycle.
+
+```
+WARN  Refs problem: /documents/en/posts/refs-broken.md
+  $author: reference /authors/does-not-exist does not resolve
+```
+
+A pending-validation map keyed by entity id is re-evaluated every cycle — entries whose targets finally appear clear themselves; new failures get added. The current state is exposed via the `mikser://schemas/pending` MCP resource so editors, dashboards, and AI agents can ask "what's currently broken?" without scraping logs.
+
+`onError: 'fail'` in the config applies only to schema-shape mismatches against the Zod schema — never to ref failures, which are always warnings because they are always recoverable through subsequent edits.
+
+### Working with refs from the frontend
+
+References behave differently in three layers per ADR-0007 A3:
+
+| Layer | Shape |
+|---|---|
+| Source files on disk | `$author: /authors/dick` |
+| Catalog (in-memory) | preserved canonical `$`-keys |
+| Templates / render context | normalized — `$` stripped, you do `{{ meta.author }}` |
+| SDK responses | normalized — you read `entity.meta.author` |
+
+So a Vue/React/Svelte component reading `useDocument` always sees `meta.author` as a plain string, regardless of whether the source used `author:` or `$author:`. Existing templates and SDK code keep working unchanged.
+
+To get the resolved entity inline (instead of just the href string) ask the api to `expand` it — see [`mikser-io-sdk-api`](https://github.com/almero-digital-marketing/mikser-io-sdk-api)'s `expand` parameter. One round-trip, full graph context, type-safe via the generated `.d.ts`.
+
+### What about graph-shaped queries?
+
+For "which entities reference this one?", "what does this entity link to?", and atomic rename cascade, the engine maintains an inverse-reference index at `runtime.refs.*`. The same data is exposed via MCP tools (`mikser_refs_inbound`, `_outbound`, `_broken`, `_rename`) and the `mikser://refs/index` resource. The index is engine-level (not a plugin) — see ADR-0006's four-test analysis in ADR-0007 §B9 — so it's always available with no plugin-coordination required. This schemas plugin currently does its own catalog walk for re-evaluation; a future optimisation will use `runtime.refs.inboundFor(ref)` to look up exactly which pending entries are affected when a target appears mid-cycle.
+
+## Conventions
+
+- **One schema file per layout**, named after the layout: `schemas/article.js`, `schemas/product.js`, etc.
+- **Default export is the Zod schema.** No registration boilerplate.
+- **Optional `revision`** export — bump to invalidate the type cache deliberately. (mikser's journal handles incremental builds normally, but this gives you a manual override if needed.)
+- **HMR**: edit a schema file while `mikser --watch` is running and the plugin re-loads it, re-validates affected entities, and re-emits the `.d.ts`.
+
+## Configuration reference
+
+```js
+schemas: {
+    // Folder containing the schema modules. Default: 'schemas'.
+    schemasFolder: 'schemas',
+
+    // Where to write the generated TypeScript declaration file.
+    // Path is relative to the working folder; default 'entities.d.ts'.
+    typesFile: 'entities.d.ts',
+
+    // How to behave when an entity fails its schema.
+    //   'warn' — log, continue.            (default)
+    //   'fail' — throw, exit non-zero.
+    //   'off'  — skip validation entirely.
+    onError: 'warn',
+
+    // Dotted path on the entity that holds the layout name. The
+    // filename stem of each schema file is matched against this value.
+    // REQUIRED. No default. Pick 'meta.layout' for SSG projects, or
+    // 'meta.component' for SPA projects (no rendered HTML, no layout).
+    schemaKey: 'meta.layout',
+}
+```
+
+## Lifecycle hooks used
+
+The plugin hooks into:
+
+| Hook | What it does |
+|---|---|
+| `onLoaded` | Resolves config paths, ensures `schemasFolder` exists, registers the schema-folder watcher. Also registers the `mikser://schemas/pending` MCP resource when an MCP substrate is available. |
+| `onSync('schemas', ...)` | Loads / reloads / unloads schema modules as files appear in `schemasFolder`. Cache-busted dynamic import so HMR works. |
+| `onValidate([CREATE, UPDATE], ...)` | Looks up the schema by `entity.meta[schemaKey]` and runs `.safeParse(entity.meta)`. Returns the error message string in `'warn'` mode, throws in `'fail'` mode. Skips silently when `schemaKey` is unset (the finalize warning surfaces the off state). Used for **schema-shape validation only**; ref validation is deferred (see below). |
+| `onFinalized` | Two passes: (1) walks every entity in the catalog and runs ref validation (shape, collision, existence) — see [ADR-0007 A6](https://github.com/almero-digital-marketing/mikser-io/blob/main/documentation/decisions/0007-references-declaration-and-expansion.md). All transitions are logged; stable repeats are silent. (2) If anything changed in the schemas map this run, re-emits the `.d.ts`. |
+
+The split between schema validation (`onValidate`, per-entity at create/update) and ref validation (`onFinalized`, full-catalog re-eval per cycle) matches the two failure modes' timing characteristics: schema shape is a property of one entity in isolation; ref resolution depends on the whole catalog's current state, which is only fully visible after `onPersist`.
+
+No engine changes, no new lifecycle phases — the plugin lives entirely on top of the existing engine API.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,579 @@
+// mikser-io-schemas
+//
+// Zod-backed entity validation for mikser-io. Schemas live as plain .js
+// modules in `schemas/` — one per layout — and validate the `meta`
+// front-matter of every loaded entity that uses that layout. A
+// TypeScript declaration file is regenerated on every build so SDK
+// consumers get typed access to entity meta.
+//
+// Layout matching:
+//   schemas/article.js  →  entities where meta.layout === 'article'
+//
+// Configuration:
+//   schemas: {
+//       schemasFolder: 'schemas',        // default
+//       typesFile:     'entities.d.ts',  // emitted at workingFolder root
+//       onError:       'warn',           // 'warn' | 'fail' | 'off'
+//       schemaKey:     'meta.layout',    // REQUIRED. Dotted front-matter
+//                                        // path that names the schema to
+//                                        // validate against. No default —
+//                                        // pick the field your project
+//                                        // actually uses for dispatch:
+//                                        // SSG projects typically pass
+//                                        // 'meta.layout'; SPA projects
+//                                        // (no rendered HTML, no layout)
+//                                        // typically pass 'meta.component'.
+//                                        // When unset, validation is off
+//                                        // and every loaded schema
+//                                        // triggers a finalize warning.
+//   }
+//
+// Behavior:
+//   - 'warn' (default): log validation errors, leave the entity in the
+//     catalog. Right for migrating an existing project; loud enough to
+//     notice, soft enough to not block deploys.
+//   - 'fail': any validation error throws — the entity is marked invalid
+//     by the lifecycle and the build surfaces a non-zero exit.
+//   - 'off':  validate nothing. Schemas still load (so the .d.ts emit
+//     still runs) but entity contents are not checked. Useful when types
+//     are the only thing you care about.
+//
+// Reference handling:
+//   References between entities are plain href strings (see
+//   mikser-io-sdk-vue's useDocument / useHref). A schema field for a
+//   reference is just z.string() — no special reference type. This keeps
+//   schemas portable and avoids coupling the validation layer to the
+//   resolution layer.
+
+import path from 'node:path'
+import { mkdir, readdir } from 'node:fs/promises'
+import _ from 'lodash'
+import { extractRefs, isRefKey, findEntities } from 'mikser-io'
+import { writeTypes } from './src/typegen.js'
+
+// Friendly per-issue messages — overrides Zod's defaults for the cases
+// where Zod's wording is technically correct but reads awkwardly for
+// people editing markdown. Returning `{ message }` overrides for that
+// issue; falling through to ctx.defaultError keeps Zod's text.
+//
+// String codes (not zod's ZodIssueCode imports) so the plugin keeps
+// zod as a peer dependency with no direct require — every schema
+// already brings its own zod.
+function friendlyErrorMap(issue, ctx) {
+    switch (issue.code) {
+        case 'invalid_type':
+            if (issue.received === 'undefined') return { message: 'is missing' }
+            return { message: `expected ${issue.expected}, got ${issue.received}` }
+        case 'too_small':
+            if (issue.type === 'string') return { message: `is too short (min ${issue.minimum} chars)` }
+            if (issue.type === 'number') return { message: `is too small (min ${issue.minimum})` }
+            if (issue.type === 'array')  return { message: `needs at least ${issue.minimum} item${issue.minimum === 1 ? '' : 's'}` }
+            break
+        case 'too_big':
+            if (issue.type === 'string') return { message: `is too long (max ${issue.maximum} chars)` }
+            if (issue.type === 'number') return { message: `is too large (max ${issue.maximum})` }
+            if (issue.type === 'array')  return { message: `has too many items (max ${issue.maximum})` }
+            break
+        case 'invalid_string':
+            if (issue.validation === 'email') return { message: 'is not a valid email' }
+            if (issue.validation === 'url')   return { message: 'is not a valid URL' }
+            if (issue.validation === 'uuid')  return { message: 'is not a valid UUID' }
+            if (issue.validation === 'regex') return { message: 'does not match the required pattern' }
+            break
+        case 'invalid_enum_value':
+            return { message: `must be one of: ${(issue.options ?? []).join(', ')}` }
+        case 'unrecognized_keys': {
+            const keys = issue.keys ?? []
+            return { message: `unknown field${keys.length === 1 ? '' : 's'}: ${keys.join(', ')}` }
+        }
+        case 'invalid_union':
+        case 'invalid_union_discriminator':
+            return { message: 'does not match any expected shape' }
+    }
+    return { message: ctx.defaultError }
+}
+
+export default ({
+    runtime,
+    onLoaded,
+    onValidate,
+    onFinalized,
+    onSync,
+    watch,
+    useLogger,
+    matchEntity,
+    constants: { OPERATION, ACTION },
+}) => {
+    const collection = 'schemas'
+    const type = 'schema'
+
+    // schema name → { name, schema, source, revision }
+    const schemas = {}
+
+    // Names of schemas that actually matched at least one entity during
+    // the run. Anything in `schemas` but missing from `usedSchemas` at
+    // finalize triggers a warning — catches the silent-skip failure
+    // mode where validation is configured but never runs (wrong
+    // schemaKey, typo, missing front-matter, no docs with that
+    // dispatch token).
+    const usedSchemas = new Set()
+
+    // Generated .d.ts gets stamped from a stable journal-of-edits, not
+    // wall-clock time — wrote() flips true on any schema-folder sync so
+    // onFinalized knows it needs to re-emit.
+    let dirty = true
+
+    // Reference-validation state. Per ADR-0007 A6 we never error on ref
+    // problems — they're routine mid-edit state (article saved before
+    // its author, entity renamed leaving N referencing entities
+    // temporarily broken). Instead we keep the open issues by entity id
+    // and re-evaluate every cycle, so newly-resolved refs auto-clear and
+    // newly-broken refs surface promptly.
+    //
+    //   pending = Map<entityId, RefIssue[]>
+    //   RefIssue = { kind: 'shape'|'collision'|'missing', path, ...detail }
+    //
+    // Logging is transition-based: a warning fires the first time an
+    // entity's ref-issue set differs from what's already recorded, and
+    // a tidy "cleared" info fires when an entity that previously had
+    // issues comes back clean. Subsequent cycles with the same set are
+    // silent to keep log noise down.
+    const pending = new Map()
+
+    function getSchemaName(entity, schemaKey) {
+        return _.get(entity, schemaKey)
+    }
+
+    // Walk meta looking for $-keys whose values are neither strings nor
+    // string arrays. Skips array elements that aren't strings — those
+    // produce per-element issues. Only walks plain objects; arrays of
+    // objects are walked too.
+    function findShapeIssues(meta) {
+        const issues = []
+        walk(meta, '')
+        return issues
+
+        function walk(node, prefix) {
+            if (node === null || typeof node !== 'object') return
+            if (Array.isArray(node)) {
+                for (let i = 0; i < node.length; i++) {
+                    walk(node[i], prefix ? `${prefix}.${i}` : String(i))
+                }
+                return
+            }
+            for (const [k, v] of Object.entries(node)) {
+                const here = prefix ? `${prefix}.${k}` : k
+                if (isRefKey(k)) {
+                    if (typeof v === 'string') {
+                        // valid
+                    } else if (Array.isArray(v)) {
+                        const badIdx = v.findIndex(x => typeof x !== 'string')
+                        if (badIdx >= 0) {
+                            issues.push({
+                                kind: 'shape',
+                                path: here,
+                                detail: `array element at index ${badIdx} is not a string`,
+                            })
+                        }
+                    } else {
+                        issues.push({
+                            kind: 'shape',
+                            path: here,
+                            detail: `value must be string or string array, got ${v === null ? 'null' : typeof v}`,
+                        })
+                    }
+                } else {
+                    walk(v, here)
+                }
+            }
+        }
+    }
+
+    // Walk meta looking for collisions — sibling keys where both `key`
+    // and `$key` are declared in the same object. Per ADR-0007 A4 the
+    // $-version wins in the projection deterministically; we surface a
+    // warning so editors know they have orphaned non-ref state.
+    function findCollisionIssues(meta) {
+        const issues = []
+        walk(meta, '')
+        return issues
+
+        function walk(node, prefix) {
+            if (node === null || typeof node !== 'object') return
+            if (Array.isArray(node)) {
+                for (let i = 0; i < node.length; i++) {
+                    walk(node[i], prefix ? `${prefix}.${i}` : String(i))
+                }
+                return
+            }
+            const dollarStems = new Set()
+            const plainKeys   = new Set()
+            for (const k of Object.keys(node)) {
+                if (isRefKey(k)) dollarStems.add(k.slice(1))
+                else plainKeys.add(k)
+            }
+            for (const stem of dollarStems) {
+                if (plainKeys.has(stem)) {
+                    const here = prefix ? `${prefix}.${stem}` : stem
+                    issues.push({
+                        kind: 'collision',
+                        path: here,
+                        detail: `both \`${stem}\` and \`$${stem}\` declared; $-version wins in render`,
+                    })
+                }
+            }
+            for (const [k, v] of Object.entries(node)) {
+                walk(v, prefix ? `${prefix}.${k}` : k)
+            }
+        }
+    }
+
+    // Check whether a ref string resolves to an entity in the catalog.
+    // The convention (ADR-0007 A2) is hrefs — leading slash, no
+    // extension — but the catalog keys entities by id (which for source-
+    // file entities includes the extension). We tolerate both forms so a
+    // ref like `/authors/dick` matches an entity at `/authors/dick.md`.
+    async function refExists(ref) {
+        const matches = await findEntities(e =>
+            !!e && (
+                e.id === ref ||
+                e.meta?.href === ref ||
+                (typeof e.id === 'string' && e.id.replace(/\.[^./]+$/, '') === ref)
+            ),
+        )
+        return matches.length > 0
+    }
+
+    async function validateEntityRefs(entity) {
+        const issues = []
+        if (!entity?.meta || typeof entity.meta !== 'object') return issues
+
+        issues.push(...findShapeIssues(entity.meta))
+        issues.push(...findCollisionIssues(entity.meta))
+
+        // Existence check runs over the valid string refs only — shape
+        // issues already flag the malformed ones, no double-warning.
+        for (const { path: refPath, ref } of extractRefs(entity.meta)) {
+            if (!(await refExists(ref))) {
+                issues.push({ kind: 'missing', path: refPath, ref })
+            }
+        }
+        return issues
+    }
+
+    function formatIssueLine(issue) {
+        switch (issue.kind) {
+            case 'shape':     return `  ${issue.path}: ${issue.detail}`
+            case 'collision': return `  ${issue.path}: ${issue.detail}`
+            case 'missing':   return `  ${issue.path}: reference ${issue.ref} does not resolve`
+            default:          return `  ${issue.path}: ${JSON.stringify(issue)}`
+        }
+    }
+
+    function issueSet(issues) {
+        return new Set(issues.map(i => `${i.kind}:${i.path}:${i.ref ?? ''}:${i.detail ?? ''}`))
+    }
+
+    function issuesEqual(a, b) {
+        if (a.length !== b.length) return false
+        const sa = issueSet(a)
+        for (const k of issueSet(b)) {
+            if (!sa.has(k)) return false
+        }
+        return true
+    }
+
+    // Load (or reload) a single schema file. Used both for the initial
+    // folder scan in onLoaded and for live onSync CREATE/UPDATE events.
+    // Returns true on successful load (caller can flip `dirty`).
+    async function loadSchemaFile(name, source) {
+        const logger = useLogger()
+        try {
+            const mod = await import(`${source}?stamp=${Date.now()}`)
+            const schema = mod.default
+            if (!schema || typeof schema.safeParse !== 'function') {
+                logger.error(
+                    'Schema %s: default export is not a Zod schema (no safeParse method)',
+                    name,
+                )
+                return false
+            }
+            schemas[name] = { name, schema, source, revision: mod.revision ?? 1 }
+            dirty = true
+            logger.info('Schema loaded: %s', name)
+            return true
+        } catch (err) {
+            logger.error('Schema %s: load failed: %s', name, err.message)
+            return false
+        }
+    }
+
+    onLoaded(async () => {
+        const logger = useLogger()
+        const config = runtime.config.schemas ?? {}
+
+        runtime.options.schemas = config.schemasFolder || collection
+        runtime.options.schemasFolder = path.join(
+            runtime.options.workingFolder,
+            runtime.options.schemas,
+        )
+        runtime.options.schemasTypesFile = path.join(
+            runtime.options.workingFolder,
+            config.typesFile || 'entities.d.ts',
+        )
+
+        await mkdir(runtime.options.schemasFolder, { recursive: true })
+        logger.info('Schemas folder: %s', runtime.options.schemasFolder)
+        logger.info('Schemas types:  %s', runtime.options.schemasTypesFile)
+
+        // Initial scan — load every existing schema file. Chokidar (started
+        // by watch() below) defaults to ignoreInitial: true and only runs
+        // in --watch mode at all, so without this loop a cold start would
+        // silently ignore every schema already on disk.
+        const entries = await readdir(runtime.options.schemasFolder, { withFileTypes: true })
+        const schemaFiles = entries
+            .filter(entry => entry.isFile())
+            .filter(entry => entry.name.endsWith('.js') || entry.name.endsWith('.mjs'))
+        for (const entry of schemaFiles) {
+            const name = entry.name.replace(path.extname(entry.name), '')
+            const source = path.join(runtime.options.schemasFolder, entry.name)
+            await loadSchemaFile(name, source)
+        }
+
+        watch(collection, runtime.options.schemasFolder)
+    })
+
+    // Discover schema modules. Each file in schemasFolder becomes one
+    // schema keyed by its filename stem ('article.js' → 'article').
+    // The default export must be a Zod schema (anything with a
+    // `.safeParse()` method is treated as one — we don't `instanceof`
+    // ZodType so users can pass a `.refine(...)`/`.transform(...)` chain
+    // or even a custom validator with a safeParse-shaped surface).
+    //
+    // onSync fires from chokidar events after the initial scan. Files
+    // already on disk at startup are picked up by the readdir loop in
+    // onLoaded.
+    onSync(collection, async ({ action, context }) => {
+        if (!context.relativePath) return false
+        const { relativePath } = context
+        if (!relativePath.endsWith('.js') && !relativePath.endsWith('.mjs')) return false
+
+        const logger = useLogger()
+        const name = relativePath.replace(path.extname(relativePath), '')
+        const source = path.join(runtime.options.schemasFolder, relativePath)
+
+        switch (action) {
+            case ACTION.CREATE:
+            case ACTION.UPDATE: {
+                await loadSchemaFile(name, source)
+                return true
+            }
+            case ACTION.DELETE: {
+                if (schemas[name]) {
+                    delete schemas[name]
+                    dirty = true
+                    logger.info('Schema removed: %s', name)
+                }
+                return true
+            }
+        }
+        return false
+    })
+
+    // Reference validation runs in `onFinalized` because that's the
+    // earliest phase where the catalog is fully populated:
+    //
+    //   process    — yaml / front-matter plugins parse `meta`
+    //   processed  — layouts plugin annotates entities
+    //   persist    — entries flow into the catalog (findEntities works
+    //                from here onwards)
+    //   render / postprocess
+    //   finalize  ← here. We can walk findEntities() and resolve refs.
+    //
+    // The earlier `onValidate` hook doesn't work for source documents
+    // because it fires at createEntity time, before front-matter has
+    // populated `meta`. Earlier process-phase hooks see only the current
+    // cycle's mutations through the journal, but ref resolution needs
+    // the *catalog* — which entities currently exist — and that's the
+    // post-persist view.
+    //
+    // Per ADR-0007 A6 ref validation is always WARNINGS, never errors.
+    // `config.onError: 'fail'` does not apply — broken refs are routine
+    // mid-edit state, not unrecoverable failures.
+    //
+    // Logging is transition-based: a warning fires the first time an
+    // entity's issue set appears or changes, and a tidy "cleared" info
+    // fires when an entity that previously had issues comes back clean.
+    // Stable repeats are silent so a single broken ref doesn't flood the
+    // log on every cycle.
+
+    // Validate per-entity on CREATE/UPDATE. Returning a string surfaces
+    // it as a validator warning via mikser's onValidate semantics;
+    // throwing fails the entry. Mode picked from runtime.config.schemas.onError.
+    onValidate([OPERATION.CREATE, OPERATION.UPDATE], async entry => {
+        const config = runtime.config.schemas ?? {}
+        const mode = config.onError ?? 'warn'
+        if (mode === 'off') return
+
+        // `schemaKey` is the dotted front-matter path that names the
+        // schema to validate against. Required — no default. SSG
+        // projects typically pass 'meta.layout' (same field mikser uses
+        // for template dispatch); SPA projects pass 'meta.component'
+        // since their docs have no layout. Anything else works too —
+        // e.g. 'meta.type' if your schemas key off a separate
+        // content-type field. When unset, validation is off; the
+        // finalize hook below warns about every loaded schema so the
+        // off state is loud, not silent.
+        const schemaKey = config.schemaKey
+        if (!schemaKey) return
+        const entity = entry.entity
+        if (!entity || !entity.meta) return
+
+        const schemaName = getSchemaName(entity, schemaKey)
+        if (!schemaName) return
+
+        const definition = schemas[schemaName]
+        if (!definition) return                 // no schema for this name — silently skip
+
+        usedSchemas.add(schemaName)
+
+        const result = definition.schema.safeParse(entity.meta, { errorMap: friendlyErrorMap })
+        if (result.success) return
+
+        // Multi-line message: one issue per line, source identified up
+        // front. Logs and thrown errors both render this readably; an
+        // editor scanning the log can spot exactly which file + which
+        // field needs attention. Single-line variant felt cramped on
+        // docs with several violations.
+        const sourceId = entity.id || '<unknown source>'
+        const lines = result.error.issues
+            .map(i => `  - ${i.path.join('.') || '<root>'}: ${i.message}`)
+        const message = `schema(${schemaName}) ${sourceId}:\n${lines.join('\n')}`
+
+        if (mode === 'fail') {
+            throw new Error(message)
+        }
+        return message                          // 'warn' — surfaces via mikser's logger
+    })
+
+    onFinalized(async () => {
+        const logger = useLogger()
+        const entities = await findEntities()
+        const stillPresent = new Set()
+        for (const entity of entities) {
+            if (!entity?.id) continue
+            stillPresent.add(entity.id)
+
+            const newIssues = await validateEntityRefs(entity)
+            const oldIssues = pending.get(entity.id) ?? []
+
+            if (!issuesEqual(newIssues, oldIssues)) {
+                if (newIssues.length > 0) {
+                    logger.warn(
+                        'Refs problem: %s\n%s',
+                        entity.id,
+                        newIssues.map(formatIssueLine).join('\n'),
+                    )
+                } else if (oldIssues.length > 0) {
+                    logger.info('Refs cleared: %s', entity.id)
+                }
+            }
+
+            if (newIssues.length > 0) pending.set(entity.id, newIssues)
+            else                       pending.delete(entity.id)
+        }
+        // Drop pending entries for entities that have been deleted from
+        // the catalog — they can't be re-validated, and keeping them in
+        // pending would leak forever.
+        for (const id of [...pending.keys()]) {
+            if (!stillPresent.has(id)) pending.delete(id)
+        }
+    })
+
+    // Expose the current pending-validation list via the MCP substrate so
+    // editors, dashboards, and AI agents can ask "what's currently
+    // broken?" without scraping logs. Read-only snapshot of the in-memory
+    // pending Map.
+    onLoaded(() => {
+        const mcp = runtime.options.mcp
+        if (!mcp) return
+        try {
+            mcp.registerResource(
+                'mikser-schemas-pending',
+                'mikser://schemas/pending',
+                {
+                    title: 'Pending schema-validation issues',
+                    description: 'Per-entity reference issues currently flagged by mikser-io-schemas — shape problems, collisions, missing targets. Re-evaluated each cycle, so entries clear when their targets appear and new entries surface as references break.',
+                    mimeType: 'application/json',
+                },
+                async (uri) => ({
+                    contents: [{
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: JSON.stringify({
+                            count: pending.size,
+                            entries: Array.from(pending.entries()).map(([id, issues]) => ({
+                                id,
+                                issues: issues.map(i => ({ kind: i.kind, path: i.path, ref: i.ref, detail: i.detail })),
+                            })),
+                        }, null, 2),
+                    }],
+                }),
+            )
+        } catch (err) {
+            useLogger().debug('mikser://schemas/pending registration skipped: %s', err.message)
+        }
+    })
+
+    // Regenerate the .d.ts at the end of every build. Idempotent — only
+    // rewrites if something actually changed in the schemas map.
+    onFinalized(async () => {
+        const logger = useLogger()
+        const config = runtime.config.schemas ?? {}
+        const mode = config.onError ?? 'warn'
+
+        // Unused-schema warning: every loaded schema that never matched
+        // an entity during the run is almost certainly a config mistake
+        // — schemaKey not set at all, or pointing at a field your
+        // front-matter doesn't declare, or a typo in either the schema
+        // filename or the dispatch value, or simply no docs of that
+        // kind. Silent skip would let a project ship with validation
+        // effectively off, so we surface it at finalize. Suppressed
+        // when mode is 'off' (the user opted out explicitly).
+        if (mode !== 'off' && Object.keys(schemas).length > 0) {
+            const schemaKey = config.schemaKey
+            const unused = Object.keys(schemas).filter(n => !usedSchemas.has(n))
+            for (const name of unused) {
+                if (!schemaKey) {
+                    logger.warn(
+                        'Schema "%s" loaded but `schemas.schemaKey` is not set — validation is off. Set it to the front-matter path that names the schema, e.g. \'meta.layout\' (SSG) or \'meta.component\' (SPA).',
+                        name,
+                    )
+                } else {
+                    logger.warn(
+                        'Schema "%s" loaded but never matched any entity — check `schemaKey` (currently \'%s\') or verify front-matter declares { %s: \'%s\' }',
+                        name, schemaKey, schemaKey.replace(/^meta\./, ''), name,
+                    )
+                }
+            }
+        }
+
+        if (!dirty) return
+        try {
+            await writeTypes({
+                schemas,
+                outputPath: runtime.options.schemasTypesFile,
+            })
+            dirty = false
+            logger.info(
+                'Schemas types emitted: %d schemas → %s',
+                Object.keys(schemas).length,
+                runtime.options.schemasTypesFile,
+            )
+        } catch (err) {
+            logger.error('Schemas types emit failed: %s', err.message)
+        }
+    })
+
+    return { collection, type }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "mikser-io-schemas",
+  "version": "0.6.0",
+  "description": "Zod-backed entity validation and TypeScript type generation for mikser-io",
+  "main": "index.js",
+  "type": "module",
+  "files": [
+    "index.js",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almero-digital-marketing/mikser-io-schemas.git"
+  },
+  "keywords": [
+    "mikser",
+    "mikser-io",
+    "zod",
+    "schema",
+    "validation",
+    "typescript"
+  ],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/almero-digital-marketing/mikser-io-schemas/issues"
+  },
+  "homepage": "https://github.com/almero-digital-marketing/mikser-io-schemas#readme",
+  "peerDependencies": {
+    "mikser-io": "^8.2.0",
+    "zod": "^4.0.0"
+  }
+}

package/src/typegen.js

@@ -0,0 +1,102 @@
+// Emit a TypeScript declaration file describing the entity meta shape for
+// each registered schema. The generated file is plain text — we don't
+// invoke the TypeScript compiler — so consumers don't need tsc installed.
+//
+// The shape is:
+//
+//   import type { z } from 'zod'
+//   import articleSchema from './schemas/article.js'
+//   import productSchema from './schemas/product.js'
+//
+//   export type ArticleMeta = z.infer<typeof articleSchema>
+//   export type ProductMeta = z.infer<typeof productSchema>
+//
+//   export interface LayoutMap {
+//       article: ArticleMeta
+//       product: ProductMeta
+//   }
+//
+//   export type LayoutName = keyof LayoutMap
+//   export type MetaByLayout<L extends LayoutName> = LayoutMap[L]
+//
+// SDK consumers can then write:
+//
+//   import type { MetaByLayout } from './entities'
+//   const { document } = useDocument<{ meta: MetaByLayout<'article'> }>(id)
+//
+// or build a discriminated union over layouts for narrow typing.
+
+import path from 'node:path'
+import { writeFile, mkdir } from 'node:fs/promises'
+
+function pascalCase(name) {
+    return name
+        .split(/[-_/.]+/)
+        .filter(Boolean)
+        .map(part => part[0].toUpperCase() + part.slice(1))
+        .join('')
+}
+
+/**
+ * Write the .d.ts to `outputPath` based on the loaded schemas.
+ *
+ * @param {object} opts
+ * @param {Record<string, { name: string, source: string }>} opts.schemas
+ *   Map of layout name → { name, source } (source is the absolute path to
+ *   the schema module, used to compute a relative import).
+ * @param {string} opts.outputPath  Absolute path to the .d.ts target.
+ */
+export async function writeTypes({ schemas, outputPath }) {
+    await mkdir(path.dirname(outputPath), { recursive: true })
+
+    const entries = Object.entries(schemas).sort(([a], [b]) => a.localeCompare(b))
+    if (entries.length === 0) {
+        // Still emit something so downstream type-checking doesn't break
+        // when the project is mid-migration with zero schemas yet.
+        const empty = [
+            '// Generated by mikser-io-schemas. Do not edit by hand.',
+            '',
+            'export interface LayoutMap {}',
+            'export type LayoutName = keyof LayoutMap',
+            'export type MetaByLayout<L extends LayoutName> = LayoutMap[L]',
+            '',
+        ].join('\n')
+        await writeFile(outputPath, empty, 'utf8')
+        return
+    }
+
+    const outDir = path.dirname(outputPath)
+    const imports = []
+    const typeAliases = []
+    const mapLines = []
+
+    for (const [layout, { source }] of entries) {
+        const ident = `${pascalCase(layout)}Schema`
+        const metaAlias = `${pascalCase(layout)}Meta`
+        let importPath = path.relative(outDir, source).replace(/\\/g, '/')
+        if (!importPath.startsWith('.')) importPath = `./${importPath}`
+
+        imports.push(`import ${ident} from '${importPath}'`)
+        typeAliases.push(`export type ${metaAlias} = z.infer<typeof ${ident}>`)
+        mapLines.push(`    '${layout}': ${metaAlias}`)
+    }
+
+    const body = [
+        '// Generated by mikser-io-schemas. Do not edit by hand.',
+        '',
+        "import type { z } from 'zod'",
+        ...imports,
+        '',
+        ...typeAliases,
+        '',
+        'export interface LayoutMap {',
+        ...mapLines,
+        '}',
+        '',
+        'export type LayoutName = keyof LayoutMap',
+        'export type MetaByLayout<L extends LayoutName> = LayoutMap[L]',
+        '',
+    ].join('\n')
+
+    await writeFile(outputPath, body, 'utf8')
+}