@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/engine/detect-project/scripts/check_runtime_coverage.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+'use strict';
+
+// Detect high-confidence client-rendered application mounts in files referenced
+// by project_map routes/layouts. Every distinct mount must own a runtime_chrome
+// recipe or carry an explicit reasoned ignore entry.
+
+const fs = require('fs');
+const path = require('path');
+
+function die(message) {
+    console.error(`ERROR: ${message}`);
+    process.exit(2);
+}
+
+const mapPath = process.argv[2];
+const projectDir = process.argv[3];
+const jsonIndex = process.argv.indexOf('--json');
+const reportPath = jsonIndex >= 0 ? process.argv[jsonIndex + 1] : null;
+if (!mapPath || !projectDir) die('usage: check_runtime_coverage.js <project_map.json> <project_dir> [--json report.json]');
+
+let projectMap;
+try {
+    projectMap = JSON.parse(fs.readFileSync(mapPath, 'utf8'));
+} catch (err) {
+    die(`cannot read project map: ${err.message}`);
+}
+
+const mountSignals = [
+    ['initialize-app', /(?:\.|\b)initialize(?:Editor|App|Application)\s*\(/],
+    ['react-root', /\b(?:createRoot|hydrateRoot)\s*\(|ReactDOM\s*\.\s*(?:render|hydrate)\s*\(/],
+    ['vue-app', /\bcreateApp\s*\([^)]*\)\s*\.\s*mount\s*\(|\bnew\s+Vue\s*\(/],
+    ['angular-bootstrap', /\bangular\s*\.\s*bootstrap\s*\(/],
+    ['explicit-dom-mount', /\b(?:mount|hydrate)\s*\(\s*(?:document\.(?:getElementById|querySelector)|['"`]#[^'"`]+['"`])/],
+];
+
+function norm(value) {
+    if (typeof value !== 'string' || !value.trim()) return null;
+    const clean = value.split(/[?#]/, 1)[0].replace(/^\.\//, '');
+    const abs = path.resolve(projectDir, clean);
+    const root = path.resolve(projectDir) + path.sep;
+    if (!abs.startsWith(root) || !fs.existsSync(abs) || !fs.statSync(abs).isFile()) return null;
+    return path.relative(projectDir, abs).split(path.sep).join('/');
+}
+
+const sources = new Map();
+function addSource(value, consumer) {
+    const rel = norm(value);
+    if (!rel) return;
+    if (!sources.has(rel)) sources.set(rel, new Set());
+    sources.get(rel).add(consumer);
+}
+
+for (const layout of Array.isArray(projectMap.layouts) ? projectMap.layouts : []) {
+    addSource(layout && layout.path, `layout:${layout && (layout.name || layout.path)}`);
+}
+for (const [key, route] of Object.entries(projectMap.route_index || {})) {
+    if (!route || typeof route !== 'object') continue;
+    for (const field of ['controller', 'primary_view', 'view', 'source_file']) addSource(route[field], `route:${key}`);
+    for (const rel of route.partials_expanded || []) addSource(rel, `route:${key}`);
+}
+
+const candidates = [];
+for (const [rel, consumers] of sources) {
+    let source;
+    try {
+        const stat = fs.statSync(path.join(projectDir, rel));
+        if (stat.size > 2 * 1024 * 1024) continue;
+        source = fs.readFileSync(path.join(projectDir, rel), 'utf8');
+    } catch (_) {
+        continue;
+    }
+    const signals = mountSignals.filter(([, re]) => re.test(source)).map(([name]) => name);
+    if (signals.length) candidates.push({ source_file: rel, signals, consumers: [...consumers].sort() });
+}
+
+const layouts = Array.isArray(projectMap.layouts) ? projectMap.layouts : [];
+const errors = [];
+const schemaV3 = Number(projectMap.schema_version) >= 3;
+const schemaV4 = Number(projectMap.schema_version) >= 4;
+const schemaV5 = Number(projectMap.schema_version) >= 5;
+const ignoredValue = (projectMap.runtime_surface_coverage || {}).ignored;
+const ignored = ignoredValue === undefined ? [] : ignoredValue;
+if (!Array.isArray(ignored)) errors.push('runtime_surface_coverage.ignored must be an array');
+const validIgnored = Array.isArray(ignored) ? ignored : [];
+
+function nonempty(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+
+function stringArray(value, { nonemptyArray = false } = {}) {
+    return Array.isArray(value)
+        && (!nonemptyArray || value.length > 0)
+        && value.every(nonempty);
+}
+
+function label(layout) {
+    return layout && (layout.name || layout.path) || '?';
+}
+
+// Schema v3 turns runtime_chrome from a descriptive hint into an enforceable
+// rendering contract. Keep older cached maps working, but reject v3 recipes
+// that can be satisfied by empty tags or that omit a load-bearing app state.
+if (schemaV3) {
+    const kebab = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+    for (const layout of layouts.filter(item => item && item.runtime_chrome)) {
+        const owner = label(layout);
+        const recipe = layout.runtime_chrome;
+        const regions = Array.isArray(recipe.regions) ? recipe.regions : [];
+        const states = Array.isArray(recipe.states) ? recipe.states : [];
+        const regionIds = regions.map(region => region && region.id);
+        const stateIds = states.map(state => state && state.id);
+
+        if (!nonempty(recipe.app)) errors.push(`runtime_chrome layout '${owner}' requires a non-empty app`);
+        if (!nonempty(recipe.mode_note)) errors.push(`runtime_chrome layout '${owner}' requires a non-empty mode_note`);
+        if (!stringArray(recipe.source_files, { nonemptyArray: true })) errors.push(
+            `runtime_chrome layout '${owner}' requires non-empty source_files`);
+        const mount = norm(layout.path);
+        const topSources = new Set((Array.isArray(recipe.source_files) ? recipe.source_files : [])
+            .map(norm).filter(Boolean));
+        if (!mount || !topSources.has(mount)) errors.push(
+            `runtime_chrome layout '${owner}' source_files must include its layout mount '${layout.path || '?'}'`);
+        if (!regions.length) errors.push(`runtime_chrome layout '${owner}' requires at least one region`);
+        if (!states.length) errors.push(`runtime_chrome layout '${owner}' requires at least one state`);
+
+        if (regionIds.some(id => !nonempty(id) || !kebab.test(id))
+            || new Set(regionIds).size !== regionIds.length) errors.push(
+            `runtime_chrome layout '${owner}' requires unique kebab-case region ids`);
+        if (stateIds.some(id => !nonempty(id) || !kebab.test(id))
+            || new Set(stateIds).size !== stateIds.length) errors.push(
+            `runtime_chrome layout '${owner}' requires unique kebab-case state ids`);
+
+        for (const region of regions) {
+            const id = region && region.id || '?';
+            if (!region || !nonempty(region.region)) errors.push(`runtime region '${id}' requires a non-empty region label`);
+            if (schemaV4) {
+                const items = region && region.items;
+                const itemIds = Array.isArray(items) ? items.map(item => item && item.id) : [];
+                if (!Array.isArray(items) || !items.length || items.some(item => !item
+                    || !nonempty(item.id) || !kebab.test(item.id) || !nonempty(item.description))
+                    || new Set(itemIds).size !== itemIds.length) errors.push(
+                    `schema-v4 runtime region '${id}' requires ordered items with unique kebab-case id and non-empty description`);
+                if (schemaV5 && (!Array.isArray(items) || items.some(item => !nonempty(item.kind) || !kebab.test(item.kind)
+                    || !Array.isArray(item.required_strings) || !item.required_strings.every(nonempty)))) errors.push(
+                    `schema-v5 runtime region '${id}' items require kebab-case kind and required_strings`);
+                if (schemaV5 && Array.isArray(items) && region.placement === 'right' && region.ui_strings.length >= 4
+                    && items.length < 4) errors.push(
+                    `schema-v5 right-panel region '${id}' must inventory its navigable rows as atomic items`);
+                if (schemaV5 && Array.isArray(items) && typeof region.placement === 'string' && region.placement.startsWith('overlay-')) {
+                    const kinds = new Set(items.map(item => item.kind));
+                    if (!kinds.has('group-heading') || !kinds.has('selection-row') || !kinds.has('actions')) errors.push(
+                        `schema-v5 grouped overlay region '${id}' requires atomic group-heading, selection-row, and actions items`);
+                    const itemText = items.flatMap(item => [item.description, ...(item.required_strings || [])]).join(' ');
+                    if (/\b(?:no changes?|unchanged)\b/i.test(itemText)) errors.push(
+                        `schema-v5 overlay region '${id}' must list concrete changed entities, not unchanged rows`);
+                }
+            } else if (!region || !stringArray(region.items, { nonemptyArray: true })) errors.push(
+                `runtime region '${id}' requires non-empty items`);
+            if (!region || !nonempty(region.appearance)) errors.push(`runtime region '${id}' requires a non-empty appearance`);
+            if (!region || typeof region.required !== 'boolean') errors.push(`runtime region '${id}' requires a boolean required flag`);
+            if (!region || !Array.isArray(region.ui_strings) || !region.ui_strings.every(nonempty)) errors.push(
+                `runtime region '${id}' requires a ui_strings array of non-empty strings`);
+            if (!region || !Array.isArray(region.required_strings) || !region.required_strings.every(nonempty)) errors.push(
+                `runtime region '${id}' requires a required_strings array of non-empty strings`);
+            if (region && typeof region.placement === 'string' && region.placement.startsWith('overlay-')) {
+                if (!Array.isArray(region.required_strings) || region.required_strings.length < 2) errors.push(
+                    `overlay runtime region '${id}' requires at least two required_strings`);
+                if (!Array.isArray(region.items) || region.items.length < 3) errors.push(
+                    `overlay runtime region '${id}' requires at least three items`);
+            }
+            if (schemaV4 && region && region.placement === 'canvas') {
+                if (!['populated', 'empty', 'loading'].includes(region.content_mode)) errors.push(
+                    `schema-v4 canvas region '${id}' requires content_mode populated, empty, or loading`);
+                if (!['required', 'optional', 'none'].includes(region.media_expectation)) errors.push(
+                    `schema-v4 canvas region '${id}' requires media_expectation required, optional, or none`);
+                if (!Number.isInteger(region.max_selected_outlines) || region.max_selected_outlines < 0) errors.push(
+                    `schema-v4 canvas region '${id}' requires a non-negative max_selected_outlines integer`);
+                const assets = region.representative_assets;
+                if (!Array.isArray(assets) || assets.some(asset => !norm(asset))
+                    || new Set(assets || []).size !== (assets || []).length) errors.push(
+                    `schema-v4 canvas region '${id}' representative_assets must be unique existing repo files`);
+                if (region.media_expectation === 'required' && (!Array.isArray(assets) || !assets.length)) errors.push(
+                    `schema-v4 canvas region '${id}' requires representative_assets when media_expectation is required`);
+            }
+        }
+
+        const regionOrder = new Map(regionIds.map((id, index) => [id, index]));
+        for (const state of states) {
+            const id = state && state.id || '?';
+            const visible = state && state.visible_regions;
+            if (!Array.isArray(visible)
+                || visible.some(regionId => !regionOrder.has(regionId))
+                || new Set(visible || []).size !== (visible || []).length
+                || (visible || []).some((regionId, index) => index > 0
+                    && regionOrder.get(regionId) <= regionOrder.get(visible[index - 1]))) {
+                errors.push(`runtime state '${id}' visible_regions must be unique valid region ids in recipe order`);
+            }
+            if (!state || typeof state.screenshot_required !== 'boolean') errors.push(
+                `runtime state '${id}' requires a boolean screenshot_required flag`);
+            if (schemaV4 && (!stringArray(state && state.topic_tags, { nonemptyArray: true })
+                || !['orientation', 'primary-action', 'secondary-action', 'terminal-action']
+                    .includes(state && state.instructional_priority))) errors.push(
+                `schema-v4 runtime state '${id}' requires topic_tags and a valid instructional_priority`);
+            if (schemaV5) {
+                if (!nonempty(state.canvas_presentation)) errors.push(
+                    `schema-v5 runtime state '${id}' requires canvas_presentation`);
+                const hasToolbar = Array.isArray(visible) && regions.some(region =>
+                    visible.includes(region.id) && region.placement === 'top');
+                if (hasToolbar && ['action', 'confirm'].includes(state.kind)
+                    && (!nonempty(state.context_label)
+                        || !Array.isArray(state.required_strings)
+                        || !state.required_strings.includes(state.context_label))) errors.push(
+                    `schema-v5 runtime state '${id}' requires a concrete context_label in required_strings`);
+            }
+            if (!state || !Array.isArray(state.required_strings) || !state.required_strings.every(nonempty)) errors.push(
+                `runtime state '${id}' requires a required_strings array of non-empty strings`);
+            if (state && state.kind === 'overview' && state.screenshot_required) errors.push(
+                `runtime overview state '${id}' cannot be screenshot_required`);
+            if (state && state.screenshot_required) {
+                if (!Array.isArray(visible) || !visible.length) errors.push(
+                    `screenshot-required runtime state '${id}' must have visible_regions`);
+                const regionAssertions = regions.filter(region => (visible || []).includes(region.id))
+                    .flatMap(region => Array.isArray(region.required_strings) ? region.required_strings : []);
+                const stateAssertions = Array.isArray(state.required_strings) ? state.required_strings : [];
+                if (![...stateAssertions, ...regionAssertions].some(nonempty)) errors.push(
+                    `screenshot-required runtime state '${id}' requires a visible required string assertion`);
+            }
+        }
+
+        if (states.filter(state => state && state.screenshot_required).length > 3) errors.push(
+            `runtime_chrome layout '${owner}' has more than three screenshot-required states`);
+        for (const region of regions) {
+            const visibleInEveryState = states.length > 0
+                && states.every(state => Array.isArray(state.visible_regions) && state.visible_regions.includes(region.id));
+            if (typeof region.required === 'boolean' && region.required !== visibleInEveryState) errors.push(
+                `runtime region '${region.id || '?'}' required must be true iff it is visible in every state`);
+        }
+
+        const leftNav = regions.some(region => region && region.placement === 'left'
+            && Array.isArray(region.ui_strings) && region.ui_strings.length >= 3);
+        const canvas = regions.some(region => region && region.placement === 'canvas');
+        const confirmationOverlay = regions.some(region => region
+            && typeof region.placement === 'string' && region.placement.startsWith('overlay-')
+            && states.some(state => state && state.kind === 'confirm'
+                && Array.isArray(state.visible_regions) && state.visible_regions.includes(region.id)));
+        if (leftNav && canvas && confirmationOverlay) {
+            const actions = states.filter(state => state && state.kind === 'action');
+            const requiredActions = actions.filter(state => state.screenshot_required);
+            if (actions.length < 2) errors.push(
+                `runtime_chrome layout '${owner}' has navigation, canvas, and confirmation surfaces and requires at least two action states`);
+            if (!schemaV4 && requiredActions.length < 2) errors.push(
+                `runtime_chrome layout '${owner}' has navigation, canvas, and confirmation surfaces and requires at least two screenshot-required action states`);
+        }
+    }
+}
+
+const ignoredBySource = new Map();
+for (const item of validIgnored) {
+    const rel = item && norm(item.source_file);
+    if (!item || typeof item !== 'object' || !rel || !nonempty(item.reason) || item.reason.trim().length < 12) {
+        errors.push(`runtime_surface_coverage.ignored entries require an existing detected source_file and a specific reason (12+ characters): ${(item && item.source_file) || '?'}`);
+        continue;
+    }
+    if (ignoredBySource.has(rel)) errors.push(`runtime_surface_coverage.ignored contains duplicate source_file: ${rel}`);
+    ignoredBySource.set(rel, item.reason.trim());
+}
+const ownership = new Map();
+for (const candidate of candidates) {
+    const owners = layouts.filter(layout => {
+        if (!layout || !layout.runtime_chrome) return false;
+        if (norm(layout.path) === candidate.source_file) return true;
+        return (layout.runtime_chrome.source_files || []).some(rel => norm(rel) === candidate.source_file);
+    });
+    const ignoreReason = ignoredBySource.get(candidate.source_file) || null;
+    candidate.covered_by = owners.map(layout => layout.name || layout.path);
+    for (const layout of owners) {
+        const key = layout.name || layout.path;
+        if (!ownership.has(key)) ownership.set(key, []);
+        ownership.get(key).push(candidate.source_file);
+    }
+    candidate.ignored = ignoreReason;
+    if (owners.length > 1) errors.push(
+        `runtime mount '${candidate.source_file}' is owned by multiple runtime_chrome layouts: ${candidate.covered_by.join(', ')}`);
+    if (owners.length && ignoreReason) errors.push(
+        `runtime mount '${candidate.source_file}' cannot be both owned and ignored`);
+    if (!owners.length && !ignoreReason) errors.push(
+        `runtime mount '${candidate.source_file}' is not owned by a distinct runtime_chrome layout and has no reasoned ignore entry`);
+}
+
+for (const [owner, mounts] of ownership) {
+    if (mounts.length > 1) errors.push(
+        `runtime_chrome layout '${owner}' combines distinct mount files (${mounts.join(', ')}); give each mount its own layout/recipe`);
+}
+
+for (const item of validIgnored) {
+    const rel = item && norm(item.source_file);
+    if (!rel || !candidates.some(candidate => candidate.source_file === rel)) errors.push(
+        `runtime_surface_coverage.ignored references a file that is not a detected runtime mount: ${(item && item.source_file) || '?'}`);
+}
+
+const report = { checked: true, candidates, ignored: validIgnored, errors, all_passed: errors.length === 0 };
+if (reportPath) {
+    fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+}
+if (errors.length) {
+    console.error(`Runtime surface coverage: FAIL (${errors.length} error(s))`);
+    for (const error of errors) console.error(`  - ${error}`);
+    process.exit(1);
+}
+console.log(`Runtime surface coverage: OK (${candidates.length} mount(s), ${validIgnored.length} ignored)`);

package/engine/detect-project/scripts/check_runtime_recipe_quality.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+'use strict';
+
+// Semantic quality checks for schema-v5 runtime recipes. Coverage answers
+// "does every mount have a recipe?"; this gate answers "is the recipe concrete,
+// internally consistent, and source-backed enough to render faithfully?"
+
+const fs = require('fs');
+const path = require('path');
+
+function die(message) {
+    console.error(`ERROR: ${message}`);
+    process.exit(2);
+}
+
+const mapArg = process.argv[2];
+const projectArg = process.argv[3];
+const jsonIndex = process.argv.indexOf('--json');
+const reportArg = jsonIndex >= 0 ? process.argv[jsonIndex + 1] : null;
+if (!mapArg || !projectArg) die('usage: check_runtime_recipe_quality.js <project_map.json> <project_dir> [--json report.json]');
+
+const projectDir = path.resolve(projectArg);
+let projectMap;
+try {
+    projectMap = JSON.parse(fs.readFileSync(mapArg, 'utf8'));
+} catch (error) {
+    die(`cannot read project map: ${error.message}`);
+}
+
+function nonempty(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+
+function filePath(value) {
+    if (!nonempty(value)) return null;
+    const clean = value.replace(/^\.\//, '').split(/[?#]/, 1)[0];
+    const absolute = path.resolve(projectDir, clean);
+    const root = `${projectDir}${path.sep}`;
+    if (!absolute.startsWith(root)) return null;
+    try {
+        if (!fs.statSync(absolute).isFile()) return null;
+    } catch (_) {
+        return null;
+    }
+    return path.relative(projectDir, absolute).split(path.sep).join('/');
+}
+
+function strings(value) {
+    return Array.isArray(value) ? value.filter(nonempty) : [];
+}
+
+function allSources(recipe) {
+    return [recipe.source_files, ...(recipe.regions || []).map(region => region.source_files),
+        ...(recipe.states || []).map(state => state.source_files)].flat().filter(nonempty);
+}
+
+function rootTokens(value) {
+    if (Array.isArray(value)) return value.filter(nonempty);
+    return nonempty(value) ? value.split(/\s+/).filter(Boolean) : [];
+}
+
+const errors = [];
+const summaries = [];
+const layouts = Array.isArray(projectMap.layouts) ? projectMap.layouts : [];
+const routes = projectMap.route_index && typeof projectMap.route_index === 'object'
+    ? Object.entries(projectMap.route_index) : [];
+
+for (const layout of layouts.filter(item => item && item.runtime_chrome)) {
+    const owner = layout.name || layout.path || '?';
+    const recipe = layout.runtime_chrome;
+    const regions = Array.isArray(recipe.regions) ? recipe.regions : [];
+    const states = Array.isArray(recipe.states) ? recipe.states : [];
+    const mount = filePath(layout.path);
+    const leftNav = regions.find(region => region && region.placement === 'left'
+        && /nav|destination/i.test(`${region.id || ''} ${region.region || ''}`));
+    const toolbar = regions.find(region => region && region.placement === 'top');
+    const canvas = regions.find(region => region && region.placement === 'canvas');
+    const overlay = regions.find(region => region && String(region.placement || '').startsWith('overlay-'));
+    const complexEditor = Boolean(leftNav && toolbar && canvas && overlay);
+
+    const invalidSources = [...new Set(allSources(recipe).filter(source => !filePath(source)))];
+    if (invalidSources.length) errors.push(
+        `runtime_chrome layout '${owner}' source_files must be existing regular files, not directories or symbolic placeholders: ${invalidSources.join(', ')}`);
+
+    if (recipe.source_kind === 'knowledge'
+        && (!Array.isArray(projectMap.default_user_assumptions) || !projectMap.default_user_assumptions.length)) {
+        errors.push(`knowledge-backed runtime_chrome layout '${owner}' requires explicit default_user_assumptions`);
+    }
+
+    const navAppearance = String(leftNav && leftNav.appearance || '');
+    if (leftNav && !/\b(?:light|dark|black|white|#[0-9a-f]{3,8})\b/i.test(navAppearance)) errors.push(
+        `runtime navigation '${leftNav.id || '?'}' must record a concrete light/dark or colour treatment`);
+
+    const shellMode = `${layout.area || ''} ${recipe.mode_note || ''}`;
+    const shellHidden = /fullscreen|full-screen|shell\s+(?:is\s+)?hidden|no\s+(?:classic\s+)?(?:admin\s+)?(?:menu|toolbar)|(?:menu|toolbar)[^.;]{0,30}hidden/i.test(shellMode);
+    if (shellHidden) {
+        if (!layout.root_classes || typeof layout.root_classes !== 'object') errors.push(
+            `shell-hiding runtime_chrome layout '${owner}' requires resolved layout root_classes`);
+        const appHtml = new Set(rootTokens(projectMap.app_shell && projectMap.app_shell.root_classes
+            && projectMap.app_shell.root_classes.html));
+        const layoutHtml = rootTokens(layout.root_classes && layout.root_classes.html);
+        const leakedOffsets = layoutHtml.filter(token => appHtml.has(token)
+            && /toolbar|admin-?bar|shell|header-offset/i.test(token));
+        if (leakedOffsets.length) errors.push(
+            `shell-hiding runtime_chrome layout '${owner}' retains app-shell offset class(es): ${leakedOffsets.join(', ')}`);
+    }
+
+    const matchingRoutes = routes.filter(([, route]) => route && (
+        route.layout === owner || route.layout === layout.path || filePath(route.primary_view) === mount
+        || filePath(route.controller) === mount || filePath(route.source_file) === mount));
+    if (mount && !matchingRoutes.length) errors.push(
+        `runtime_chrome layout '${owner}' has no route pointing to its mount`);
+
+    if (complexEditor) {
+        const toolbarItems = Array.isArray(toolbar.items) ? toolbar.items : [];
+        const toolbarKinds = new Set(toolbarItems.map(item => item && item.kind));
+        if (toolbarItems.length < 5 || !['identity', 'control-group', 'document-context', 'primary-action']
+            .every(kind => toolbarKinds.has(kind))) errors.push(
+            `complex editor '${owner}' toolbar must inventory identity, editing controls, concrete document context, view controls, and primary action as at least five items`);
+
+        const canvasItems = Array.isArray(canvas.items) ? canvas.items : [];
+        const canvasSources = [...new Set(strings(canvas.source_files).map(filePath).filter(Boolean))];
+        if (canvas.content_mode === 'populated' && canvasItems.length < 3) errors.push(
+            `populated complex-editor canvas '${canvas.id || '?'}' requires at least three source-backed anatomy items`);
+        if (canvas.content_mode === 'populated' && canvasSources.filter(source => source !== mount).length < 2) errors.push(
+            `populated complex-editor canvas '${canvas.id || '?'}' requires at least two concrete content source files beyond its runtime mount`);
+
+        const documentItems = toolbarItems.filter(item => item && item.kind === 'document-context');
+        const documentLabels = new Set(documentItems.flatMap(item => strings(item.required_strings)));
+        const featureLabels = new Set(regions.flatMap(region => [region.region])
+            .concat(leftNav ? strings(leftNav.ui_strings) : [])
+            .filter(nonempty).map(value => value.toLowerCase()));
+        for (const state of states.filter(state => state && ['action', 'confirm'].includes(state.kind)
+            && strings(state.visible_regions).includes(toolbar.id))) {
+            const context = String(state.context_label || '').trim();
+            if (!documentLabels.has(context)) errors.push(
+                `runtime state '${state.id || '?'}' context_label '${context || '?'}' must match the toolbar document-context item`);
+            if (featureLabels.has(context.toLowerCase())
+                || /^(?:home|page|document|template|editor|content|design|styles?|settings|untitled)$/i.test(context)) errors.push(
+                `runtime state '${state.id || '?'}' context_label '${context}' is a generic feature label, not a concrete open document/template title`);
+        }
+
+        const actionCount = states.filter(state => state && state.kind === 'action').length;
+        const overlayItems = Array.isArray(overlay.items) ? overlay.items : [];
+        const groups = overlayItems.filter(item => item && item.kind === 'group-heading');
+        const selections = overlayItems.filter(item => item && item.kind === 'selection-row');
+        const expectedGroups = Math.min(2, actionCount);
+        if (groups.length < expectedGroups || selections.length < expectedGroups) errors.push(
+            `complex editor '${owner}' confirmation must inventory at least ${expectedGroups} changed-entity group(s) and selection row(s), matching its action families`);
+        for (const item of selections) {
+            const labels = strings(item.required_strings);
+            if (!labels.length || labels.every(value => /^(?:custom\s+)?(?:styles?|templates?|changes?|settings?)$/i.test(value))) errors.push(
+                `confirmation selection '${item.id || '?'}' requires a concrete entity name, not a generic change label`);
+        }
+
+        for (const [key, route] of matchingRoutes) {
+            const partials = strings(route.partials_expanded);
+            const invalidPartials = partials.filter(partial => !filePath(partial));
+            if (!partials.length || invalidPartials.length) errors.push(
+                `runtime route '${key}' for complex editor '${owner}' requires recursively expanded regular-file partials`);
+            const closure = new Set([route.primary_view, route.controller_action, ...partials]
+                .map(filePath).filter(Boolean));
+            const missingCanvas = canvasSources.filter(source => !closure.has(source));
+            if (missingCanvas.length) errors.push(
+                `runtime route '${key}' partial closure omits canvas source(s): ${missingCanvas.join(', ')}`);
+        }
+    }
+
+    summaries.push({ layout: owner, complex_editor: complexEditor, sources: new Set(allSources(recipe)).size,
+        regions: regions.length, states: states.length });
+}
+
+const report = { checked: true, summaries, errors, all_passed: errors.length === 0 };
+if (reportArg) {
+    const reportPath = path.resolve(reportArg);
+    fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+    fs.writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`);
+}
+if (errors.length) {
+    console.error(`Runtime recipe quality: FAIL (${errors.length} error(s))`);
+    errors.forEach(error => console.error(`  - ${error}`));
+    process.exit(1);
+}
+console.log(`Runtime recipe quality: OK (${summaries.length} recipe(s))`);