@vectoriox/iox-ui 5.60.0 → 5.61.0

package/src/generation-core/plan-wire.ts

@@ -0,0 +1,458 @@
+import { ANIMATE_IDS, DesignChoices } from '@vectoriox/iox-ui/design-core';
+import { FORM_PRESETS } from '@vectoriox/iox-ui/forms-core';
+
+import { describeShapeKey, jsonAnyOf, jsonBoolean, jsonInteger, jsonListOf, jsonOneOf, JsonSchema, jsonShapedObject, jsonText } from './json-schema';
+import { patternLinkSlots, patternOptionalParts, patternSlots, PatternGlobalPosition, SITE_PATTERNS } from './patterns';
+import {
+    ContentFieldPlan, ContentTypePlan, DataSourcePlan, FactKey, GlobalSlot, PAGE_ARCHETYPES, PagePlan, PageSectionPlan, PlanDataSourceMode, PlanDataSourceType,
+    RelativeOp, SITE_NEED_IDS, SITE_PLAN_VERSION, SitePlan, SitePlanSource, SiteLocale,
+} from './site-plan.model';
+import { SPEC_SITE_PLAN_SHAPE } from './site-spec.generated';
+import { isPlainObject, PlainObject, ShapeEntry, shapeKeys } from './shape-check';
+
+/**
+ * The plan WIRE (AI plan M1-3, vectoriox/iox-cms#45): what a model writes when it plans a site — a compact format inside
+ * the Claude API's structured-output limits (≤ 24 optional parameters and ≤ 16 unions per request; `strict-schema.ts`).
+ * The Site Plan itself (`SPEC_SITE_PLAN_SHAPE`) has 213 optional keys once every pattern is a branch, so the model never
+ * writes it: it writes this, and ONE pure `expandPlanWire` turns it into the Site Plan that `validateSitePlan` and the
+ * stage's gate judge exactly as before.
+ *
+ * - **Every key required.** A plan key that may be absent is written with its stated "none" — `''`, `0`, `false`, `[]`.
+ * - **Closed lists as enums** (patterns, page types, needs, slots, parts, forms, entrances, header/footer), from the
+ *   contract — never per-pattern branches: the gate refuses a slot or a part the chosen pattern does not have, with its path.
+ * - **Maps as lists:** slots `[{ slot, text }]`, links `[{ slot, route }]`, seed values `[{ field, value }]`, roles fixed.
+ * - **One data source object** for both kinds; `type` says which keys are read (the other kind's hold their none).
+ * - **What the model does not decide is not on the wire** (`PLAN_WIRE_DERIVED`): the look (the owner's pick), the run,
+ *   the language (the reading's), the facts (the owner's own, verbatim), the version, the home page (the page at `/`).
+ *   So the format is the same for every studio and every run — one compiled grammar, cached by the provider.
+ *
+ * ONE source: every wire key names the plan keys it carries (`refs`) and is described in the plan table's own words, and
+ * every plan key is either carried or derived (`planWireGaps()`); a key the plan shape gains breaks the builder until it
+ * is placed. The expanders translate, never repair: a value the model got wrong stays wrong, for the gate to refuse.
+ */
+
+export const PLAN_WIRE_SCHEMA_NAME = 'site_plan';
+
+export enum PlanWireEntry {
+    Plan = 'plan',
+    Business = 'business',
+    ContentType = 'contentType',
+    Roles = 'roles',
+    Field = 'field',
+    Seed = 'seed',
+    SeedValue = 'seedValue',
+    DataSource = 'dataSource',
+    Page = 'page',
+    PageSeo = 'pageSeo',
+    Section = 'section',
+    SlotText = 'slotText',
+    SlotLink = 'slotLink',
+    Globals = 'globals',
+}
+
+type PlanShapeName = keyof typeof SPEC_SITE_PLAN_SHAPE;
+
+interface WireKey {
+    /** The plan keys it carries (`entry.key`, `[field]` for a dynamic key). */
+    refs: ReadonlyArray<string>;
+    /** Its own words, when the first ref's do not fit the wire. */
+    text?: string;
+    /** What stands for "absent" (an optional plan key). */
+    none?: string;
+}
+
+const PLAN_SHAPE = SPEC_SITE_PLAN_SHAPE as unknown as Readonly<Record<string, ShapeEntry>>;
+const key = (ref: string, none?: string): WireKey => ({ refs: [ref], ...(none !== undefined ? { none } : {}) });
+
+const WIRE_KEYS: Readonly<Record<`${PlanWireEntry}`, Readonly<Record<string, WireKey>>>> = {
+    plan: {
+        business: key('plan.business'),
+        contentTypes: key('plan.contentTypes'),
+        dataSources: { refs: ['plan.dataSources'], text: 'dataSource[] — merged by alias into the org library' },
+        pages: key('plan.pages'),
+        globals: key('plan.globals'),
+    },
+    business: {
+        name: key('business.name'),
+        tagline: key('business.tagline', "''"),
+    },
+    contentType: {
+        name: key('contentType.name'),
+        label: key('contentType.label'),
+        roles: key('contentType.roles'),
+        fields: key('contentType.fields'),
+        seed: { refs: ['contentType.seed'], text: 'seed — the sample items', none: 'count 0 and no values' },
+    },
+    roles: {
+        title: key('roles.title'),
+        summary: key('roles.summary', "''"),
+        image: key('roles.image', "''"),
+        meta: key('roles.meta', "''"),
+        date: key('roles.date', "''"),
+        gallery: key('roles.gallery', "''"),
+    },
+    field: {
+        name: key('field.name'),
+        type: key('field.type'),
+        controller: key('field.controller'),
+        required: { refs: ['field.required'], text: 'boolean — the field must be filled', none: 'false' },
+        note: key('field.note', "''"),
+    },
+    seed: {
+        count: key('seed.count'),
+        sample: key('seed.sample'),
+        isPublished: key('seed.isPublished'),
+        values: { refs: ['seed.[field]'], text: "seedValue[] — one per field: the samples' value for it" },
+    },
+    seedValue: {
+        field: { refs: ['seed.[field]'], text: 'string — a field of the type' },
+        value: { refs: ['seed.[field]'], text: `string | string[] — ${describeShapeKey(PLAN_SHAPE['seed'], '[field]')} (a list for an array field)` },
+    },
+    dataSource: {
+        alias: { refs: ['cmsDataSource.alias', 'relativeDataSource.alias'] },
+        type: { refs: ['cmsDataSource.type', 'relativeDataSource.type'], text: "'cms' | 'relative' — which of the keys below are read" },
+        mode: key('cmsDataSource.mode', "'' (relative)"),
+        contentType: key('cmsDataSource.contentType', "'' (relative)"),
+        limit: key('cmsDataSource.limit', '0 (all, or relative)'),
+        filterField: { refs: ['cmsDataSource.filterByRouteParam'], text: "string — single only: the field that holds the route param's value (e.g. slug)", none: "''" },
+        routeParam: { refs: ['cmsDataSource.filterByRouteParam'], text: 'string — single only: the route param that picks the item (the :param of its page route)', none: "''" },
+        of: key('relativeDataSource.of', "'' (cms)"),
+        op: key('relativeDataSource.op', "'' (cms)"),
+        within: key('relativeDataSource.within', "'' (cms)"),
+    },
+    page: {
+        key: key('page.key'),
+        name: key('page.name'),
+        route: { refs: ['page.route'], text: `${describeShapeKey(PLAN_SHAPE['page'], 'route')}; the page at "/" is the home page` },
+        inNav: key('page.inNav', 'false'),
+        archetype: key('page.archetype', "''"),
+        need: key('page.need', "''"),
+        template: key('page.template', "''"),
+        routeSource: key('page.routeSource', "''"),
+        seo: key('page.seo'),
+        sections: key('page.sections'),
+    },
+    pageSeo: {
+        title: key('pageSeo.title', "''"),
+        description: key('pageSeo.description', "''"),
+    },
+    section: {
+        pattern: key('section.pattern'),
+        slots: { refs: ['section.slots'], text: "slotText[] — the pattern's declared slots it fills, each within its budget (site.patterns … max × site.copyLengths)", none: '[]' },
+        links: { refs: ['section.links'], text: 'slotLink[] — re-points a linked slot (a button, a link) to another page route of the plan', none: '[]' },
+        binding: key('section.binding', "''"),
+        without: key('section.without', '[]'),
+        form: key('section.form', "''"),
+        enter: key('section.enter', "'' (the look's)"),
+    },
+    slotText: {
+        slot: { refs: ['section.slots'], text: "string — one of the pattern's slots" },
+        text: { refs: ['section.slots'], text: "string — the words, in the owner's language and voice" },
+    },
+    slotLink: {
+        slot: { refs: ['section.links'], text: "string — one of the pattern's linked slots" },
+        route: { refs: ['section.links'], text: 'string — a page route of the plan (no :param)' },
+    },
+    globals: {
+        header: key('globals.header'),
+        footer: key('globals.footer'),
+    },
+};
+
+/** The plan keys the model does not write, and where the expander takes each from. */
+export const PLAN_WIRE_DERIVED: Readonly<Record<string, string>> = {
+    'plan.version': `always '${SITE_PLAN_VERSION}'`,
+    'plan.source': 'this run (the context)',
+    'plan.locale': "the reading's language (the context)",
+    'plan.design': "the owner's pick (the context)",
+    'business.facts': "the owner's own facts, verbatim (the context)",
+    'page.isHome': 'the page at "/"',
+    'page.required': "a template page's (the wizard's Pages step), never the AI's",
+    sourceTemplate: 'the AI never writes a template plan',
+    sourceAi: 'this run (the context)',
+    design: "the owner's pick (the context)",
+};
+
+const wireText = (spec: WireKey): string => {
+    const [entry, planKey] = spec.refs[0].split('.');
+    const base = spec.text ?? describeShapeKey(PLAN_SHAPE[entry], planKey);
+    return spec.none === undefined ? base : `${base} — ${spec.none} = none`;
+};
+
+/** The wire's shape table, in the plan table's words — what the model reads, and what the format is built from. */
+export const PLAN_WIRE_SHAPE: Readonly<Record<`${PlanWireEntry}`, ShapeEntry>> = Object.fromEntries(
+    Object.entries(WIRE_KEYS).map(([entry, keys]) => [entry, Object.fromEntries(Object.entries(keys).map(([k, spec]) => [k, wireText(spec)]))]),
+) as Record<`${PlanWireEntry}`, ShapeEntry>;
+
+/** Plan keys neither carried by a wire key nor derived — always empty (a spec and the builder hold it). */
+export function planWireGaps(): string[] {
+    const carried = new Set(Object.values(WIRE_KEYS).flatMap(keys => Object.values(keys).flatMap(spec => spec.refs)));
+    const gaps: string[] = [];
+    for (const [entry, shape] of Object.entries(PLAN_SHAPE)) {
+        if (PLAN_WIRE_DERIVED[entry]) continue;
+        for (const raw of Object.keys(shape)) {
+            const ref = `${entry}.${raw.replace(/\?$/, '')}`;
+            if (!carried.has(ref) && !PLAN_WIRE_DERIVED[ref]) gaps.push(ref);
+        }
+    }
+    return gaps;
+}
+
+export class PlanWireShapeError extends Error {}
+
+// ── The format ─────────────────────────────────────────────────────────────────────────────────────────────────────
+
+const unique = (values: ReadonlyArray<string>) => [...new Set(values)];
+const NONE = '';
+const orNone = (values: ReadonlyArray<string>): JsonSchema => jsonOneOf([NONE, ...values]);
+const closedOrText = (values: ReadonlyArray<string>): JsonSchema => (values.length ? jsonOneOf(values) : jsonText());
+const shaped = (entry: `${PlanWireEntry}`, properties: Record<string, JsonSchema>) => jsonShapedObject(PLAN_WIRE_SHAPE[entry], properties, `wire ${entry}`);
+
+/** The patterns a page section may use (every non-global one), in library order. */
+export function sectionPatternIds(): string[] {
+    return Object.entries(SITE_PATTERNS).filter(([, p]) => !p.global).map(([id]) => id);
+}
+
+const sectionPatterns = () => sectionPatternIds().map(id => SITE_PATTERNS[id]);
+const globalIds = (position: `${PatternGlobalPosition}`) => Object.entries(SITE_PATTERNS).filter(([, p]) => p.global === position).map(([id]) => id);
+
+export function wireFieldJsonSchema(): JsonSchema {
+    return shaped(PlanWireEntry.Field, { name: jsonText(), type: jsonText(), controller: jsonText(), required: jsonBoolean(), note: jsonText() });
+}
+
+export function wireContentTypeJsonSchema(): JsonSchema {
+    const roleKeys = shapeKeys(PLAN_WIRE_SHAPE.roles);
+    const value = shaped(PlanWireEntry.SeedValue, { field: jsonText(), value: jsonAnyOf([jsonText(), jsonListOf(jsonText())]) });
+    return shaped(PlanWireEntry.ContentType, {
+        name: jsonText(),
+        label: jsonText(),
+        roles: shaped(PlanWireEntry.Roles, Object.fromEntries(roleKeys.map(k => [k, jsonText()]))),
+        fields: jsonListOf(wireFieldJsonSchema()),
+        seed: shaped(PlanWireEntry.Seed, { count: jsonInteger(), sample: jsonBoolean(), isPublished: jsonBoolean(), values: jsonListOf(value) }),
+    });
+}
+
+export function wireDataSourceJsonSchema(): JsonSchema {
+    return shaped(PlanWireEntry.DataSource, {
+        alias: jsonText(),
+        type: jsonOneOf(Object.values(PlanDataSourceType)),
+        mode: orNone(Object.values(PlanDataSourceMode)),
+        contentType: jsonText(),
+        limit: jsonInteger(),
+        filterField: jsonText(),
+        routeParam: jsonText(),
+        of: jsonText(),
+        op: orNone(Object.values(RelativeOp)),
+        within: jsonText(),
+    });
+}
+
+export function wireSectionJsonSchema(): JsonSchema {
+    const patterns = sectionPatterns();
+    return shaped(PlanWireEntry.Section, {
+        pattern: jsonOneOf(sectionPatternIds()),
+        slots: jsonListOf(shaped(PlanWireEntry.SlotText, { slot: closedOrText(unique(patterns.flatMap(patternSlots))), text: jsonText() })),
+        links: jsonListOf(shaped(PlanWireEntry.SlotLink, { slot: closedOrText(unique(patterns.flatMap(patternLinkSlots))), route: jsonText() })),
+        binding: jsonText(),
+        without: jsonListOf(closedOrText(unique(patterns.flatMap(patternOptionalParts)))),
+        form: orNone(FORM_PRESETS.map(p => p.id)),
+        enter: orNone(ANIMATE_IDS),
+    });
+}
+
+export function wirePageJsonSchema(): JsonSchema {
+    return shaped(PlanWireEntry.Page, {
+        key: jsonText(),
+        name: jsonText(),
+        route: jsonText(),
+        inNav: jsonBoolean(),
+        archetype: orNone(Object.keys(PAGE_ARCHETYPES)),
+        need: orNone(SITE_NEED_IDS),
+        template: jsonText(),
+        routeSource: jsonText(),
+        seo: shaped(PlanWireEntry.PageSeo, { title: jsonText(), description: jsonText() }),
+        sections: jsonListOf(wireSectionJsonSchema()),
+    });
+}
+
+/** The format a model writes a plan in. The same for every studio and run: nothing in it is pinned. */
+export function planWireJsonSchema(): JsonSchema {
+    const gaps = planWireGaps();
+    if (gaps.length) throw new PlanWireShapeError(`the plan wire neither carries nor derives ${gaps.join(', ')}`);
+    return shaped(PlanWireEntry.Plan, {
+        business: shaped(PlanWireEntry.Business, { name: jsonText(), tagline: jsonText() }),
+        contentTypes: jsonListOf(wireContentTypeJsonSchema()),
+        dataSources: jsonListOf(wireDataSourceJsonSchema()),
+        pages: jsonListOf(wirePageJsonSchema()),
+        globals: shaped(PlanWireEntry.Globals, {
+            [GlobalSlot.Header]: jsonOneOf(globalIds(PatternGlobalPosition.Before)),
+            [GlobalSlot.Footer]: jsonOneOf(globalIds(PatternGlobalPosition.After)),
+        }),
+    });
+}
+
+// ── The wire → the plan ────────────────────────────────────────────────────────────────────────────────────────────
+
+/** What the plan takes from the generation, not from the model. */
+export interface PlanWireContext {
+    design: DesignChoices;
+    source: SitePlanSource;
+    /** The owner's own facts (the analysis's, as corrected), verbatim. */
+    facts?: Readonly<Partial<Record<FactKey, string>>>;
+    locale?: `${SiteLocale}`;
+}
+
+/** A value standing for "absent": `''` (or nothing at all). */
+const isNone = (v: unknown) => v === undefined || v === NONE;
+const optional = (name: string, v: unknown, none: (v: unknown) => boolean = isNone): PlainObject => (none(v) ? {} : { [name]: v });
+const emptyList = (v: unknown) => v === undefined || (Array.isArray(v) && v.length === 0);
+
+/** `[{ <keyName>, <valueName> }]` → `{ key: value }`; anything else is left for the gate to refuse. */
+function listToMap(list: unknown, keyName: string, valueName: string): unknown {
+    if (!Array.isArray(list)) return list;
+    const out: PlainObject = {};
+    for (const entry of list) {
+        if (!isPlainObject(entry) || typeof entry[keyName] !== 'string') return list;
+        out[entry[keyName] as string] = entry[valueName];
+    }
+    return out;
+}
+
+const mapToList = (map: Readonly<Record<string, unknown>> | undefined, keyName: string, valueName: string) =>
+    Object.entries(map ?? {}).map(([k, v]) => ({ [keyName]: k, [valueName]: v }));
+
+const each = (list: unknown, expand: (v: unknown) => unknown) => (Array.isArray(list) ? list.map(expand) : list);
+
+export function expandWireField(wire: unknown): ContentFieldPlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { required, note, ...rest } = wire;
+    return { ...rest, ...optional('required', required, v => v === undefined || v === false), ...optional('note', note) };
+}
+
+export function expandWireContentType(wire: unknown): ContentTypePlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { roles, fields, seed, ...rest } = wire;
+    const out: PlainObject = { ...rest, roles: isPlainObject(roles) ? Object.fromEntries(Object.entries(roles).filter(([, v]) => !isNone(v))) : roles, fields: each(fields, expandWireField) };
+    if (!isPlainObject(seed)) return seed === undefined ? out : { ...out, seed };
+    const { values, ...fixed } = seed;
+    if (fixed['count'] === 0 && emptyList(values)) return out;
+    const map = listToMap(values ?? [], 'field', 'value');
+    return { ...out, seed: isPlainObject(map) ? { ...fixed, ...map } : { ...fixed, values } };
+}
+
+export function expandWireDataSource(wire: unknown): DataSourcePlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { alias, type, mode, contentType, limit, filterField, routeParam, of, op, within, ...rest } = wire;
+    if (type === PlanDataSourceType.Cms) {
+        const filter = isNone(filterField) && isNone(routeParam) ? {} : { filterByRouteParam: { field: filterField, routeParam } };
+        return { ...rest, alias, type, mode, contentType, ...optional('limit', limit, v => v === undefined || v === 0), ...filter };
+    }
+    if (type === PlanDataSourceType.Relative) return { ...rest, alias, type, of, op, within };
+    return wire;
+}
+
+export function expandWireSection(wire: unknown): PageSectionPlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { slots, links, binding, without, form, enter, ...rest } = wire;
+    return {
+        ...rest,
+        ...optional('slots', listToMap(slots, 'slot', 'text'), v => emptyList(slots) || v === undefined),
+        ...optional('links', listToMap(links, 'slot', 'route'), v => emptyList(links) || v === undefined),
+        ...optional('binding', binding),
+        ...optional('without', without, emptyList),
+        ...optional('form', form),
+        ...optional('enter', enter),
+    };
+}
+
+export function expandWirePage(wire: unknown): PagePlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { archetype, need, template, routeSource, seo, sections, ...rest } = wire;
+    const words = isPlainObject(seo) ? { ...optional('title', seo['title']), ...optional('description', seo['description']) } : seo;
+    return {
+        ...rest,
+        ...(wire['route'] === '/' ? { isHome: true } : {}),
+        ...optional('archetype', archetype),
+        ...optional('need', need),
+        ...optional('template', template),
+        ...optional('routeSource', routeSource),
+        ...optional('seo', words, v => v === undefined || (isPlainObject(v) && Object.keys(v).length === 0)),
+        sections: each(sections, expandWireSection),
+    };
+}
+
+function expandWireBusiness(wire: unknown, facts: PlanWireContext['facts']): unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { tagline, ...rest } = wire;
+    return { ...rest, ...optional('tagline', tagline), ...(facts && Object.keys(facts).length ? { facts: { ...facts } } : {}) };
+}
+
+/**
+ * A model's plan (the wire) + what the generation decides (the look, the run, the language, the owner's facts) → the
+ * Site Plan. Pure. Translates, never repairs: whatever the answer got wrong is still wrong, for `validateSitePlan`.
+ */
+export function expandPlanWire(wire: unknown, context: PlanWireContext): SitePlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { business, contentTypes, dataSources, pages, ...rest } = wire;
+    return {
+        ...rest,
+        version: SITE_PLAN_VERSION,
+        source: { ...context.source },
+        business: expandWireBusiness(business, context.facts),
+        ...(context.locale ? { locale: context.locale } : {}),
+        design: { ...context.design },
+        contentTypes: each(contentTypes, expandWireContentType),
+        dataSources: each(dataSources, expandWireDataSource),
+        pages: each(pages, expandWirePage),
+    };
+}
+
+// ── The plan → the wire ────────────────────────────────────────────────────────────────────────────────────────────
+
+export function fieldToWire(field: ContentFieldPlan): PlainObject {
+    return { name: field.name, type: field.type, controller: field.controller, required: field.required ?? false, note: field.note ?? NONE };
+}
+
+export function contentTypeToWire(type: ContentTypePlan): PlainObject {
+    const roles = Object.fromEntries(shapeKeys(PLAN_WIRE_SHAPE.roles).map(role => [role, (type.roles as Readonly<Record<string, string>>)[role] ?? NONE]));
+    const { count = 0, sample = false, isPublished = false, ...values } = type.seed ?? {};
+    return {
+        name: type.name, label: type.label, roles, fields: type.fields.map(fieldToWire),
+        seed: { count, sample, isPublished, values: mapToList(values, 'field', 'value') },
+    };
+}
+
+export function dataSourceToWire(source: DataSourcePlan): PlainObject {
+    const blank = { alias: source.alias, type: source.type, mode: NONE, contentType: NONE, limit: 0, filterField: NONE, routeParam: NONE, of: NONE, op: NONE, within: NONE };
+    if (source.type === PlanDataSourceType.Relative) return { ...blank, of: source.of, op: source.op, within: source.within };
+    return {
+        ...blank, mode: source.mode, contentType: source.contentType, limit: source.limit ?? 0,
+        filterField: source.filterByRouteParam?.field ?? NONE, routeParam: source.filterByRouteParam?.routeParam ?? NONE,
+    };
+}
+
+export function sectionToWire(section: PageSectionPlan): PlainObject {
+    return {
+        pattern: section.pattern, slots: mapToList(section.slots, 'slot', 'text'), links: mapToList(section.links, 'slot', 'route'),
+        binding: section.binding ?? NONE, without: [...(section.without ?? [])], form: section.form ?? NONE, enter: section.enter ?? NONE,
+    };
+}
+
+export function pageToWire(page: PagePlan): PlainObject {
+    return {
+        key: page.key, name: page.name, route: page.route, inNav: page.inNav ?? false, archetype: page.archetype ?? NONE, need: page.need ?? NONE,
+        template: page.template ?? NONE, routeSource: page.routeSource ?? NONE,
+        seo: { title: page.seo?.title ?? NONE, description: page.seo?.description ?? NONE }, sections: page.sections.map(sectionToWire),
+    };
+}
+
+/** The plan → the wire: what a model would have written (the plan edits' prompt shows it; fakes and evals write it). */
+export function planToWire(plan: SitePlan): PlainObject {
+    return {
+        business: { name: plan.business.name, tagline: plan.business.tagline ?? NONE },
+        contentTypes: plan.contentTypes.map(contentTypeToWire),
+        dataSources: plan.dataSources.map(dataSourceToWire),
+        pages: plan.pages.map(pageToWire),
+        globals: { ...plan.globals },
+    };
+}

package/src/generation-core/public-api.ts

@@ -27,7 +27,8 @@ export * from './plan-data';
 export * from './showcase';
 export * from './site-build-run';
 export * from './ai-run';
-export * from './site-plan-schema';
+export * from './plan-wire';
+export * from './strict-schema';
 export * from './plan-edits';
 export * from './plan-words';
 export * from './audit-site';

package/src/generation-core/strict-schema.ts

@@ -0,0 +1,96 @@
+import type { JsonSchema } from './json-schema';
+
+/**
+ * What a structured-output request costs the provider's grammar compiler, counted the way the Claude API counts it
+ * (platform.claude.com/docs/en/build-with-claude/structured-outputs, "Schema complexity limits", read 2026-10-27):
+ * "Total optional parameters across all strict tool schemas and JSON output schemas. Each parameter not listed in
+ * `required` counts toward this limit" (24); "Total parameters that use `anyOf` or type arrays (for example,
+ * `"type": ["string", "null"]`) across all strict schemas" (16); "Maximum number of tools with `strict: true`" (20).
+ * The limits are per REQUEST — every strict schema in it together. The ONE counter: the specs hold every schema iox-cms
+ * sends to it, and the fake Claude API refuses with it exactly as Claude does — the plan stage once sent 213 optional
+ * parameters and every suite stayed green because the fake accepted anything (vectoriox/iox-cms#45).
+ */
+
+export const STRICT_SCHEMA_LIMITS = { strictTools: 20, optional: 24, unions: 16 } as const;
+
+/** What a schema iox-cms sends may use — half of each limit, so a step can gain a field (or a strict tool) without a 400. */
+export const STRICT_SCHEMA_BUDGET = { optional: 12, unions: 8 } as const;
+
+export interface StrictSchemaComplexity {
+    /** Properties not listed in their object's `required`, every object of every schema. */
+    optional: number;
+    /** Nodes using `anyOf` or a type array. */
+    unions: number;
+    /** Tools with `strict: true` (a JSON output format is not a tool). */
+    strictTools: number;
+    /** What the strict mode does not support, each with its path (`pages.items.properties.route: minLength`). */
+    unsupported: string[];
+}
+
+/** The keywords the docs list as not supported ("Numerical constraints", "String constraints", "Array constraints beyond `minItems` of 0 or 1"). */
+const UNSUPPORTED_KEYWORDS: ReadonlyArray<string> = [
+    'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf', 'minLength', 'maxLength', 'maxItems', 'uniqueItems', 'contains',
+    'minContains', 'maxContains', 'prefixItems', 'patternProperties', 'propertyNames', 'dependentSchemas', 'if', 'then', 'else', 'not',
+];
+const NESTED_LISTS: ReadonlyArray<string> = ['anyOf', 'allOf', 'oneOf'];
+const NESTED_MAPS: ReadonlyArray<string> = ['properties', '$defs', 'definitions'];
+
+const isObject = (v: unknown): v is JsonSchema => !!v && typeof v === 'object' && !Array.isArray(v);
+
+function count(node: unknown, path: string, out: StrictSchemaComplexity): void {
+    if (!isObject(node)) return;
+    const at = (key: string) => (path ? `${path}.${key}` : key);
+    if (Array.isArray(node['anyOf']) || Array.isArray(node['type'])) out.unions++;
+    const properties = isObject(node['properties']) ? node['properties'] : null;
+    if (node['type'] === 'object' || properties) {
+        const required = new Set(Array.isArray(node['required']) ? (node['required'] as string[]) : []);
+        out.optional += Object.keys(properties ?? {}).filter(key => !required.has(key)).length;
+        if (node['additionalProperties'] !== false) out.unsupported.push(`${at('additionalProperties')}: must be false`);
+    }
+    for (const key of UNSUPPORTED_KEYWORDS) if (key in node) out.unsupported.push(`${at(key)}: not supported`);
+    if ('minItems' in node && node['minItems'] !== 0 && node['minItems'] !== 1) out.unsupported.push(`${at('minItems')}: only 0 or 1`);
+    if (Array.isArray(node['enum']) && (node['enum'] as unknown[]).some(v => v !== null && typeof v === 'object')) out.unsupported.push(`${at('enum')}: complex types`);
+    if (typeof node['$ref'] === 'string' && !(node['$ref'] as string).startsWith('#')) out.unsupported.push(`${at('$ref')}: external`);
+    for (const key of NESTED_MAPS) {
+        if (isObject(node[key])) for (const [name, child] of Object.entries(node[key] as JsonSchema)) count(child, at(`${key}.${name}`), out);
+    }
+    for (const key of NESTED_LISTS) {
+        if (Array.isArray(node[key])) (node[key] as unknown[]).forEach((child, i) => count(child, at(`${key}[${i}]`), out));
+    }
+    if (isObject(node['items'])) count(node['items'], at('items'), out);
+    if (isObject(node['additionalProperties'])) count(node['additionalProperties'], at('additionalProperties'), out);
+}
+
+/** The cost of ONE request's strict schemas together: its JSON output format and its strict tools' input schemas. */
+export function strictSchemaComplexity(schemas: ReadonlyArray<JsonSchema>, strictTools = 0): StrictSchemaComplexity {
+    const out: StrictSchemaComplexity = { optional: 0, unions: 0, strictTools, unsupported: [] };
+    schemas.forEach((schema, i) => count(schema, schemas.length > 1 ? `[${i}]` : '', out));
+    return out;
+}
+
+/** A refusal shaped like the Claude API's (HTTP 400, `invalid_request_error`). */
+export interface StrictSchemaRefusal {
+    status: 400;
+    type: 'invalid_request_error';
+    message: string;
+}
+
+/**
+ * The 400 the Claude API answers a request over its limits with, or null. The optional-parameter message is the one
+ * Claude answered on 2026-10-27, verbatim; the union, strict-tool and unsupported messages follow its shape (not yet
+ * captured).
+ */
+export function strictSchemaRefusal(complexity: StrictSchemaComplexity): StrictSchemaRefusal | null {
+    const refuse = (message: string): StrictSchemaRefusal => ({ status: 400, type: 'invalid_request_error', message });
+    if (complexity.unsupported.length) return refuse(`Invalid schema: ${complexity.unsupported.join('; ')}`);
+    if (complexity.strictTools > STRICT_SCHEMA_LIMITS.strictTools) {
+        return refuse(`Too many strict tools (${complexity.strictTools}). Reduce the number of tools with strict: true (limit: ${STRICT_SCHEMA_LIMITS.strictTools}).`);
+    }
+    if (complexity.optional > STRICT_SCHEMA_LIMITS.optional) {
+        return refuse(`Schemas contains too many optional parameters (${complexity.optional}), which would make grammar compilation inefficient. Reduce the number of optional parameters in your tool schemas (limit: ${STRICT_SCHEMA_LIMITS.optional}).`);
+    }
+    if (complexity.unions > STRICT_SCHEMA_LIMITS.unions) {
+        return refuse(`Schemas contains too many parameters with union types (${complexity.unions}), which would make grammar compilation inefficient. Reduce the number of parameters with union types in your tool schemas (limit: ${STRICT_SCHEMA_LIMITS.unions}).`);
+    }
+    return null;
+}