@vectoriox/iox-ui 5.60.0 → 5.62.0

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

@@ -0,0 +1,544 @@
+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, #47): 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, and a compiled
+ * grammar under the size Claude refuses — measured as ≤ 60 properties; `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.
+ *
+ * - **Written in two PARTS, one request each** (#47 — the whole plan in one format was 64 properties): the **structure** (the business,
+ *   the content types, the data sources) and then the **pages** (the pages, the header and footer), written knowing the
+ *   structure. Every top-level key belongs to exactly one part (`part` below); `expandPlanWire` puts the parts together.
+ *
+ * - **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 `[{ role, field }]`.
+ * - **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.
+ */
+
+/** The plan's parts, in the order they are written: the pages bind to the structure's sources and types. */
+export enum PlanPart {
+    Structure = 'structure',
+    Pages = 'pages',
+}
+
+export const PLAN_PARTS: ReadonlyArray<PlanPart> = [PlanPart.Structure, PlanPart.Pages];
+
+/** Each part's format name (a request names the format it asks for). */
+export const PLAN_WIRE_PART_SCHEMA_NAMES: Readonly<Record<PlanPart, string>> = {
+    [PlanPart.Structure]: 'site_plan_structure',
+    [PlanPart.Pages]: 'site_plan_pages',
+};
+
+export enum PlanWireEntry {
+    Plan = 'plan',
+    Business = 'business',
+    ContentType = 'contentType',
+    RoleField = 'roleField',
+    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;
+    /** The part a top-level key is written in. */
+    part?: PlanPart;
+}
+
+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 inPart = (part: PlanPart, spec: WireKey): WireKey => ({ ...spec, part });
+/** The roles a content type's fields play (`roles` of the plan shape), in the plan shape's order. */
+const ROLE_KEYS: ReadonlyArray<string> = shapeKeys(PLAN_SHAPE['roles']);
+const roleWords = ROLE_KEYS.map(role => `${role}: ${describeShapeKey(PLAN_SHAPE['roles'], role).replace(/^string — /, '')}`).join('; ');
+
+const WIRE_KEYS: Readonly<Record<`${PlanWireEntry}`, Readonly<Record<string, WireKey>>>> = {
+    plan: {
+        business: inPart(PlanPart.Structure, key('plan.business')),
+        contentTypes: inPart(PlanPart.Structure, key('plan.contentTypes')),
+        dataSources: inPart(PlanPart.Structure, { refs: ['plan.dataSources'], text: 'dataSource[] — merged by alias into the org library' }),
+        pages: inPart(PlanPart.Pages, key('plan.pages')),
+        globals: inPart(PlanPart.Pages, key('plan.globals')),
+    },
+    business: {
+        name: key('business.name'),
+        tagline: key('business.tagline', "''"),
+    },
+    contentType: {
+        name: key('contentType.name'),
+        label: key('contentType.label'),
+        roles: { refs: ['contentType.roles'], text: `roleField[] — ${describeShapeKey(PLAN_SHAPE['contentType'], 'roles').replace(/^roles — /, '')}; a role no field plays is left out` },
+        fields: key('contentType.fields'),
+        seed: { refs: ['contentType.seed'], text: 'seed — the sample items', none: 'count 0 and no values' },
+    },
+    roleField: {
+        role: { refs: ROLE_KEYS.map(role => `roles.${role}`), text: `${ROLE_KEYS.map(r => `'${r}'`).join(' | ')} — ${roleWords}` },
+        field: { refs: ['roles.title'], text: 'string — the field of the type that plays it' },
+    },
+    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>;
+
+/** Each part's top-level keys, from the ONE wire table. */
+export const PLAN_PART_KEYS: Readonly<Record<PlanPart, ReadonlyArray<string>>> = Object.fromEntries(
+    PLAN_PARTS.map(part => [part, Object.entries(WIRE_KEYS.plan).filter(([, spec]) => spec.part === part).map(([k]) => k)]),
+) as Record<PlanPart, string[]>;
+
+/** The keys of a shape entry, but these. */
+const shapeWithout = (entry: ShapeEntry, keys: ReadonlyArray<string>): ShapeEntry =>
+    Object.fromEntries(Object.entries(entry).filter(([k]) => !keys.includes(k.replace(/\?$/, ''))));
+
+/**
+ * The part a plan path is the answer of (`contentTypes[1].seed.title` → structure, `pages[0].sections[2]` → pages). A
+ * path no part writes — the root (the composer), or a key the generation decides — is the LAST part's: it is written
+ * knowing everything before it.
+ */
+export function planPartOfPath(path: string): PlanPart {
+    const top = path.split(/[.[]/, 1)[0];
+    return PLAN_PARTS.find(part => PLAN_PART_KEYS[part].includes(top)) ?? PLAN_PARTS[PLAN_PARTS.length - 1];
+}
+
+/** 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() });
+}
+
+/** What an object of the wire travels without when its children are written as their own entries (a plan edit's). */
+export interface WireOptions {
+    /** false: a content type without its `fields`, a page without its `sections` (each added by an edit after it). */
+    children?: boolean;
+}
+
+/** The keys an entry leaves out under `options`. */
+const CHILD_KEYS: Readonly<Partial<Record<`${PlanWireEntry}`, string>>> = { contentType: 'fields', page: 'sections' };
+const childless = (entry: `${PlanWireEntry}`, options: WireOptions) => (options.children === false && CHILD_KEYS[entry] ? [CHILD_KEYS[entry]!] : []);
+
+/** The shape an entry is written in, under `options`. */
+function wireEntryShape(entry: `${PlanWireEntry}`, options: WireOptions = {}): ShapeEntry {
+    return shapeWithout(PLAN_WIRE_SHAPE[entry], childless(entry, options));
+}
+
+const shapedAs = (entry: `${PlanWireEntry}`, options: WireOptions, properties: Record<string, JsonSchema>) => {
+    const left = childless(entry, options);
+    return jsonShapedObject(wireEntryShape(entry, options), Object.fromEntries(Object.entries(properties).filter(([k]) => !left.includes(k))), `wire ${entry}`);
+};
+
+export function wireContentTypeJsonSchema(options: WireOptions = {}): JsonSchema {
+    const value = shaped(PlanWireEntry.SeedValue, { field: jsonText(), value: jsonAnyOf([jsonText(), jsonListOf(jsonText())]) });
+    return shapedAs(PlanWireEntry.ContentType, options, {
+        name: jsonText(),
+        label: jsonText(),
+        roles: jsonListOf(shaped(PlanWireEntry.RoleField, { role: jsonOneOf(ROLE_KEYS), field: 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(options: WireOptions = {}): JsonSchema {
+    return shapedAs(PlanWireEntry.Page, options, {
+        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()),
+    });
+}
+
+const PLAN_TOP_SCHEMAS: Readonly<Record<string, () => JsonSchema>> = {
+    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 plan's top-level shape for one part (its keys only) — what that part's request shows and is built from. */
+export function planWirePartShape(part: PlanPart): ShapeEntry {
+    return Object.fromEntries(Object.entries(PLAN_WIRE_SHAPE.plan).filter(([k]) => PLAN_PART_KEYS[part].includes(k)));
+}
+
+/**
+ * The format a model writes one part of a plan in — one request each (vectoriox/iox-cms#47). The same for every studio
+ * and run: nothing in it is pinned, so the provider compiles each part's grammar once.
+ */
+export function planWirePartJsonSchema(part: PlanPart): JsonSchema {
+    const gaps = planWireGaps();
+    if (gaps.length) throw new PlanWireShapeError(`the plan wire neither carries nor derives ${gaps.join(', ')}`);
+    const missing = Object.keys(WIRE_KEYS.plan).filter(k => !PLAN_TOP_SCHEMAS[k] || !WIRE_KEYS.plan[k].part);
+    if (missing.length) throw new PlanWireShapeError(`the plan wire's ${missing.join(', ')} has no part or no format`);
+    return jsonShapedObject(planWirePartShape(part), Object.fromEntries(PLAN_PART_KEYS[part].map(k => [k, PLAN_TOP_SCHEMAS[k]()])), `wire plan ${part}`);
+}
+
+// ── 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, options: WireOptions = {}): ContentTypePlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { roles, fields, seed, ...rest } = options.children === false ? { fields: [], ...wire } : wire;
+    const out: PlainObject = { ...rest, roles: listToMap(roles, 'role', 'field'), 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, options: WireOptions = {}): PagePlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { archetype, need, template, routeSource, seo, sections, ...rest } = options.children === false ? { sections: [], ...wire } : 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 plan on the wire, by part — what each request answered. A part not written yet is absent. */
+export type PlanWireParts = Partial<Record<PlanPart, unknown>>;
+
+/**
+ * A model's plan (its parts, on the wire) + what the generation decides (the look, the run, the language, the owner's
+ * facts) → the Site Plan. Pure. Translates, never repairs: whatever an answer got wrong is still wrong, for
+ * `validateSitePlan` — a part that is not an object is the result itself, a part not written yet leaves its keys out
+ * (the validator then names them, at their own paths).
+ */
+export function expandPlanWire(parts: PlanWireParts, context: PlanWireContext): SitePlan | unknown {
+    const written = PLAN_PARTS.filter(part => parts[part] !== undefined).map(part => parts[part]);
+    const odd = written.find(value => !isPlainObject(value));
+    if (odd !== undefined) return odd;
+    const wire: PlainObject = Object.assign({}, ...(written as PlainObject[]));
+    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, options: WireOptions = {}): PlainObject {
+    const played = type.roles as Readonly<Record<string, string | undefined>>;
+    const roles = ROLE_KEYS.filter(role => played[role]).map(role => ({ role, field: played[role] }));
+    const { count = 0, sample = false, isPublished = false, ...values } = type.seed ?? {};
+    return {
+        name: type.name, label: type.label, roles, ...(options.children === false ? {} : { 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, options: WireOptions = {}): 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 },
+        ...(options.children === false ? {} : { sections: page.sections.map(sectionToWire) }),
+    };
+}
+
+const PLAN_TO_WIRE: Readonly<Record<string, (plan: SitePlan) => unknown>> = {
+    business: plan => ({ name: plan.business.name, tagline: plan.business.tagline ?? NONE }),
+    contentTypes: plan => plan.contentTypes.map(type => contentTypeToWire(type)),
+    dataSources: plan => plan.dataSources.map(dataSourceToWire),
+    pages: plan => plan.pages.map(page => pageToWire(page)),
+    globals: plan => ({ ...plan.globals }),
+};
+
+/** One part of the plan on the wire: what that part's request would have answered. */
+export function planPartToWire(plan: SitePlan, part: PlanPart): PlainObject {
+    return Object.fromEntries(PLAN_PART_KEYS[part].map(k => [k, PLAN_TO_WIRE[k](plan)]));
+}
+
+/** The plan → the wire, by part: what a model would have written (the change prompt shows it; fakes and evals write it). */
+export function planToWire(plan: SitePlan): Record<PlanPart, PlainObject> {
+    return Object.fromEntries(PLAN_PARTS.map(part => [part, planPartToWire(plan, part)])) as Record<PlanPart, PlainObject>;
+}

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';