@vectoriox/iox-ui 5.61.0 → 5.62.0

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

@@ -4,8 +4,8 @@ import {
 import { patternById, patternOptionalParts, patternSlots, patternTakesBinding } from './patterns';
 import {
     contentTypeToWire, dataSourceToWire, expandWireContentType, expandWireDataSource, expandWireField, expandWirePage, expandWireSection, fieldToWire,
-    pageToWire, PlanWireShapeError, sectionPatternIds, sectionToWire, wireContentTypeJsonSchema, wireDataSourceJsonSchema, wireFieldJsonSchema,
-    wirePageJsonSchema, wireSectionJsonSchema,
+    pageToWire, PLAN_PARTS, PlanPart, PlanWireShapeError, sectionPatternIds, sectionToWire, wireContentTypeJsonSchema, wireDataSourceJsonSchema,
+    wireFieldJsonSchema, WireOptions, wirePageJsonSchema, wireSectionJsonSchema,
 } from './plan-wire';
 import {
     ContentFieldPlan, ContentTypePlan, DataSourcePlan, PagePlan, PageSectionPlan, PlanDataSourceMode, PlanDataSourceType, SitePlan,
@@ -68,10 +68,35 @@ export const PLAN_EDIT_SHAPE: Readonly<Record<`${PlanEditOp}`, ShapeEntry>> = {
     [PlanEditOp.SwapPattern]: { op: "'swapPattern'", page: 'string — a page key', index: 'integer — the section', pattern: 'string — the pattern it becomes (its slots kept where the new one has them)' },
     [PlanEditOp.SetSlot]: { op: "'setSlot'", page: 'string — a page key', index: 'integer — the section', slot: "string — one of the pattern's slots", text: "string — the words, in the owner's language and voice" },
     [PlanEditOp.AddContentType]: { op: "'addContentType'", contentType: 'contentType — a unique name', 'dataSources?': 'dataSource[] — the list / single sources its pages read' },
-    [PlanEditOp.AddField]: { op: "'addField'", contentType: 'string — a content type of the plan', field: 'field', 'sample?': "string | string[] — the samples' value for it" },
+    [PlanEditOp.AddField]: { op: "'addField'", contentType: 'string — a content type of the plan', field: 'field', 'sample?': "string | string[] — the samples' value for it; absent: what the type's seed already holds for it, else ''" },
     [PlanEditOp.SetSectionData]: { op: "'setSectionData'", page: 'string — a page key', index: 'integer — the section', binding: 'string — the list source the section repeats' },
 };
 
+/**
+ * The plan part each op changes (vectoriox/iox-cms#47): a sentence is answered in the plan's two parts, one request each —
+ * the structure's edits first, then the pages' written knowing them.
+ */
+export const PLAN_EDIT_OP_PART: Readonly<Record<`${PlanEditOp}`, PlanPart>> = {
+    [PlanEditOp.AddPage]: PlanPart.Pages,
+    [PlanEditOp.RemovePage]: PlanPart.Pages,
+    [PlanEditOp.RenamePage]: PlanPart.Pages,
+    [PlanEditOp.MergePages]: PlanPart.Pages,
+    [PlanEditOp.MovePage]: PlanPart.Pages,
+    [PlanEditOp.AddSection]: PlanPart.Pages,
+    [PlanEditOp.RemoveSection]: PlanPart.Pages,
+    [PlanEditOp.MoveSection]: PlanPart.Pages,
+    [PlanEditOp.SwapPattern]: PlanPart.Pages,
+    [PlanEditOp.SetSlot]: PlanPart.Pages,
+    [PlanEditOp.SetSectionData]: PlanPart.Pages,
+    [PlanEditOp.AddContentType]: PlanPart.Structure,
+    [PlanEditOp.AddField]: PlanPart.Structure,
+};
+
+/** The ops written in one part, in `PlanEditOp` order. */
+export function planEditOps(part: PlanPart): PlanEditOp[] {
+    return Object.values(PlanEditOp).filter(op => PLAN_EDIT_OP_PART[op] === part);
+}
+
 export enum PlanChangeKind {
     Page = 'page',
     Section = 'section',
@@ -207,6 +232,10 @@ function findSection(d: Draft, pageAt: number, index: unknown, c: Collector, pat
 
 const setSections = (d: Draft, at: number, sections: PageSectionPlan[]) => { d.pages[at] = { ...d.pages[at], sections }; };
 
+/** A child added to a page or type the same edits added is part of that addition — the map marks the parent only. */
+const addedHere = (changed: ReadonlyArray<PlanChange>, kind: PlanChangeKind, at: { page?: string; name?: string }) =>
+    changed.some(ch => ch.kind === kind && ch.action === PlanChangeAction.Added && (kind === PlanChangeKind.Page ? ch.page === at.page : ch.name === at.name));
+
 /** One handler per op — a data table, never an if-chain. */
 const APPLY: Readonly<Record<`${PlanEditOp}`, Apply>> = {
     [PlanEditOp.AddPage]: (d, e, c, path, changed) => {
@@ -260,7 +289,7 @@ const APPLY: Readonly<Record<`${PlanEditOp}`, Apply>> = {
         const index = e.at === undefined ? sections.length : clamp(e.at, sections.length);
         sections.splice(index, 0, e.section as PageSectionPlan);
         setSections(d, at, sections);
-        changed.push({ kind: PlanChangeKind.Section, action: PlanChangeAction.Added, page: d.pages[at].key, index });
+        if (!addedHere(changed, PlanChangeKind.Page, { page: d.pages[at].key })) changed.push({ kind: PlanChangeKind.Section, action: PlanChangeAction.Added, page: d.pages[at].key, index });
     },
     [PlanEditOp.RemoveSection]: (d, e, c, path, changed) => {
         const at = findPage(d, e.page, c, `${path}.page`);
@@ -320,9 +349,9 @@ const APPLY: Readonly<Record<`${PlanEditOp}`, Apply>> = {
         if (at < 0) return c.add(PlanEditIssueCode.UnknownContentType, `${path}.contentType`, `no content type "${String(e.contentType)}" in the plan`);
         const type = d.contentTypes[at];
         if (type.fields.some(f => f.name === e.field.name)) return c.add(PlanEditIssueCode.Duplicate, `${path}.field.name`, `"${type.name}" already has a field "${e.field.name}"`);
-        const seed = type.seed ? { ...type.seed, [e.field.name]: e.sample ?? '' } : undefined;
+        const seed = type.seed ? { ...type.seed, [e.field.name]: e.sample ?? type.seed[e.field.name] ?? '' } : undefined;
         d.contentTypes[at] = { ...type, fields: [...type.fields, e.field], ...(seed ? { seed } : {}) };
-        changed.push({ kind: PlanChangeKind.Field, action: PlanChangeAction.Added, name: `${type.name}.${e.field.name}` });
+        if (!addedHere(changed, PlanChangeKind.ContentType, { name: type.name })) changed.push({ kind: PlanChangeKind.Field, action: PlanChangeAction.Added, name: `${type.name}.${e.field.name}` });
     },
     [PlanEditOp.SetSectionData]: (d, e, c, path, changed) => {
         const at = findPage(d, e.page, c, `${path}.page`);
@@ -361,7 +390,11 @@ export function applyPlanEdits(plan: SitePlan, edits: ReadonlyArray<PlanEdit>):
 
 // ── The format a model writes edits in ─────────────────────────────────────────────────────────────────
 
-export const PLAN_EDITS_SCHEMA_NAME = 'plan_edits';
+/** Each part's answer format name. */
+export const PLAN_EDITS_PART_SCHEMA_NAMES: Readonly<Record<PlanPart, string>> = {
+    [PlanPart.Structure]: 'plan_structure_edits',
+    [PlanPart.Pages]: 'plan_page_edits',
+};
 
 /** A sentence's answer: the edits, or why the ops cannot say it (one line, in the owner's language). */
 export enum PlanEditsOutcome {
@@ -376,18 +409,28 @@ export interface PlanEditsAnswer {
     reason: string;
 }
 
-/** The answer's own keys, explained. */
-export const PLAN_EDITS_ANSWER_SHAPE: ShapeEntry = {
-    outcome: "'edits' | 'cannot' — cannot: the operations cannot do what the sentence asks",
-    edits: 'edit[] — applied in order, all or none; empty when cannot',
-    reason: "string — when cannot, ONE short line for the owner in their language (what to do instead); else ''",
+/**
+ * Each part's answer, explained. The structure is asked first, so it says whether the sentence is a plan change at all
+ * (`outcome`); the pages are asked only when it is, and write only their edits.
+ */
+export const PLAN_EDITS_ANSWER_SHAPES: Readonly<Record<PlanPart, ShapeEntry>> = {
+    [PlanPart.Structure]: {
+        outcome: "'edits' | 'cannot' — cannot: no operation of either part (below) can do what the sentence asks",
+        edits: 'edit[] — the content types and fields the sentence adds, in order; empty when it adds none, or cannot',
+        reason: "string — when cannot, ONE short line for the owner in their language (what to do instead); else ''",
+    },
+    [PlanPart.Pages]: {
+        edits: 'edit[] — the page and section edits, in order, made after the structure edits (already applied); empty when none',
+    },
 };
 
 /**
- * ONE edit on the wire (vectoriox/iox-cms#45): a flat object whose keys are ALL required — the 13 ops as `anyOf`
- * branches, each embedding whole pages, sections and content types, came to 395 optional parameters against the Claude
- * API's 24. `op` says which keys are read (`PLAN_EDIT_WIRE_KEYS`, from `PLAN_EDIT_SHAPE`); every other key holds its
- * none. A whole page, section, content type or field travels as a list of exactly one, in the plan wire's format.
+ * ONE flat edit per part on the wire (vectoriox/iox-cms#45, #47): an object whose keys are ALL required — the 13 ops as
+ * `anyOf` branches came to 395 optional parameters against the Claude API's 24, and one flat edit for all of them to 95
+ * properties, a grammar Claude refuses (≤ 60). `op` says which keys are read (`PLAN_EDIT_WIRE_KEYS`, from
+ * `PLAN_EDIT_SHAPE`); every other key holds its none. A new page, section, content type or field travels as a list of
+ * exactly one, in the plan wire's format — and an added page or content type travels WITHOUT its children: each of its
+ * sections is an `addSection` after it, each of its fields an `addField` (a new type's samples ride on its `seed`).
  */
 interface EditWireKey {
     text: string;
@@ -400,6 +443,8 @@ interface EditWireKey {
 }
 
 const NO_INDEX = -1;
+/** A new page or content type on the wire: its children are edits of their own. */
+const CHILDLESS: WireOptions = { children: false };
 
 /** A list holding exactly one object: none → absent, one → it (expanded), more → the list (the gate refuses it). */
 const oneOf = (schema: () => JsonSchema, expand: (v: unknown) => unknown, toWire: (v: any) => unknown, what: string): EditWireKey => ({
@@ -420,17 +465,22 @@ const EDIT_WIRE: Readonly<Record<string, EditWireKey>> = {
     after: textKey('addPage: the key of the page it follows in the menu'),
     into: textKey('mergePages: the page that stays'),
     from: textKey('mergePages: the page whose sections move into it, then removed'),
-    index: indexKey('the section, 0-based on its page'),
+    index: indexKey('the section, 0-based on its page (addSection: the place the new one goes)'),
     to: indexKey('movePage / moveSection: the new 0-based place'),
-    at: indexKey('addSection: its 0-based place on the page'),
     pattern: { text: 'string — swapPattern: the section pattern it becomes', none: '', schema: () => jsonOneOf(['', ...sectionPatternIds()]) },
     slot: textKey("setSlot: one of the pattern's slots"),
     text: textKey("setSlot: the words, in the owner's language and voice"),
     binding: textKey('setSectionData: the list source the section repeats'),
     contentType: textKey('addField: a content type of the plan'),
-    newPage: oneOf(wirePageJsonSchema, expandWirePage, pageToWire, 'page'),
+    newPage: {
+        ...oneOf(() => wirePageJsonSchema(CHILDLESS), v => expandWirePage(v, CHILDLESS), p => pageToWire(p, CHILDLESS), 'page'),
+        text: 'page[] — exactly one when the op takes it, WITHOUT sections: each is an addSection after it',
+    },
     newSection: oneOf(wireSectionJsonSchema, expandWireSection, sectionToWire, 'section'),
-    newContentType: oneOf(wireContentTypeJsonSchema, expandWireContentType, contentTypeToWire, 'contentType'),
+    newContentType: {
+        ...oneOf(() => wireContentTypeJsonSchema(CHILDLESS), v => expandWireContentType(v, CHILDLESS), t => contentTypeToWire(t, CHILDLESS), 'contentType'),
+        text: "contentType[] — exactly one when the op takes it, WITHOUT fields: each is an addField after it (the samples' values stay in its seed)",
+    },
     dataSources: {
         text: 'dataSource[] — addContentType: the list / single sources its pages read', none: [],
         schema: () => jsonListOf(wireDataSourceJsonSchema()),
@@ -448,7 +498,7 @@ export const PLAN_EDIT_WIRE_KEYS: Readonly<Record<`${PlanEditOp}`, Readonly<Reco
     [PlanEditOp.RenamePage]: { page: 'page', name: 'name', route: 'route' },
     [PlanEditOp.MergePages]: { into: 'into', from: 'from' },
     [PlanEditOp.MovePage]: { page: 'page', to: 'to' },
-    [PlanEditOp.AddSection]: { page: 'page', section: 'newSection', at: 'at' },
+    [PlanEditOp.AddSection]: { page: 'page', section: 'newSection', at: 'index' },
     [PlanEditOp.RemoveSection]: { page: 'page', index: 'index' },
     [PlanEditOp.MoveSection]: { page: 'page', from: 'index', to: 'to' },
     [PlanEditOp.SwapPattern]: { page: 'page', index: 'index', pattern: 'pattern' },
@@ -458,23 +508,32 @@ export const PLAN_EDIT_WIRE_KEYS: Readonly<Record<`${PlanEditOp}`, Readonly<Reco
     [PlanEditOp.SetSectionData]: { page: 'page', index: 'index', binding: 'binding' },
 };
 
+/** The wire keys a part's edit carries: every key its ops read, in `EDIT_WIRE` order. */
+export function planEditWireKeys(part: PlanPart): string[] {
+    const read = new Set(planEditOps(part).flatMap(op => Object.values(PLAN_EDIT_WIRE_KEYS[op])));
+    return Object.keys(EDIT_WIRE).filter(k => read.has(k));
+}
+
 const isEditWireNone = (wireKey: string, v: unknown) => {
     const none = EDIT_WIRE[wireKey].none;
     return v === undefined || (Array.isArray(none) ? Array.isArray(v) && v.length === 0 : v === none) || (wireKey === 'sample' && Array.isArray(v) && v.length === 0);
 };
 const noneText = (none: unknown) => (Array.isArray(none) ? '[]' : typeof none === 'string' ? "''" : String(none));
+const opsText = (part: PlanPart) => planEditOps(part).map(op => `'${op}'`).join(' | ');
+
+/** A part's flat edit, as a shape table: every key required, each with its none. */
+export function planEditWireShape(part: PlanPart): ShapeEntry {
+    return {
+        op: `${opsText(part)} — which keys below are read`,
+        ...Object.fromEntries(planEditWireKeys(part).map(k => [k, `${EDIT_WIRE[k].text} — ${noneText(EDIT_WIRE[k].none)} when the op does not read it`])),
+    };
+}
 
-/** The flat edit's shape table: every key required, each with its none. */
-export const PLAN_EDIT_WIRE_SHAPE: ShapeEntry = {
-    op: `${OPS.map(op => `'${op}'`).join(' | ')} — which keys below are read`,
-    ...Object.fromEntries(Object.entries(EDIT_WIRE).map(([k, spec]) => [k, `${spec.text} — ${noneText(spec.none)} when the op does not read it`])),
-};
-
-/** Per op, the wire keys it reads, in `PLAN_EDIT_SHAPE`'s words (`?` = may hold its none) — what the model reads. */
-export function planEditWireOps(): Record<string, Record<string, string>> {
-    return Object.fromEntries(OPS.map(op => {
-        const entry = PLAN_EDIT_SHAPE[op as PlanEditOp];
-        const keys = PLAN_EDIT_WIRE_KEYS[op as PlanEditOp];
+/** Per op of a part, the wire keys it reads, in `PLAN_EDIT_SHAPE`'s words (`?` = may hold its none) — what the model reads. */
+export function planEditWireOps(part: PlanPart): Record<string, Record<string, string>> {
+    return Object.fromEntries(planEditOps(part).map(op => {
+        const entry = PLAN_EDIT_SHAPE[op];
+        const keys = PLAN_EDIT_WIRE_KEYS[op];
         return [op, Object.fromEntries(Object.entries(keys).map(([planKey, wireKey]) => {
             const optionalKey = `${planKey}?` in entry;
             return [`${wireKey}${optionalKey ? '?' : ''}`, entry[optionalKey ? `${planKey}?` : planKey]];
@@ -497,19 +556,21 @@ export function planEditWireGaps(): string[] {
     return gaps;
 }
 
-/** The format a sentence's answer is written in: the outcome, the flat edits, the reason. */
-export function planEditsJsonSchema(): JsonSchema {
+const ANSWER_SCHEMAS: Readonly<Record<string, (part: PlanPart) => JsonSchema>> = {
+    outcome: () => jsonOneOf(Object.values(PlanEditsOutcome)),
+    reason: () => jsonText(),
+    edits: part => jsonListOf(jsonShapedObject(planEditWireShape(part), {
+        op: jsonOneOf(planEditOps(part)),
+        ...Object.fromEntries(planEditWireKeys(part).map(k => [k, EDIT_WIRE[k].schema()])),
+    }, `edit ${part}`)),
+};
+
+/** The format one part of a sentence's answer is written in — one request each (vectoriox/iox-cms#47). */
+export function planEditsJsonSchema(part: PlanPart): JsonSchema {
     const gaps = planEditWireGaps();
     if (gaps.length) throw new PlanWireShapeError(`the plan edits wire does not carry ${gaps.join(', ')}`);
-    const edit = jsonShapedObject(PLAN_EDIT_WIRE_SHAPE, {
-        op: jsonOneOf(OPS),
-        ...Object.fromEntries(Object.entries(EDIT_WIRE).map(([k, spec]) => [k, spec.schema()])),
-    }, 'edit');
-    return jsonShapedObject(PLAN_EDITS_ANSWER_SHAPE, {
-        outcome: jsonOneOf(Object.values(PlanEditsOutcome)),
-        edits: jsonListOf(edit),
-        reason: jsonText(),
-    }, 'planEdits');
+    const shape = PLAN_EDITS_ANSWER_SHAPES[part];
+    return jsonShapedObject(shape, Object.fromEntries(shapeKeys(shape).map(k => [k, ANSWER_SCHEMAS[k](part)])), `planEdits ${part}`);
 }
 
 /** One flat edit → the op's edit: the keys it reads, a none left out where the op may go without it. Never repaired. */
@@ -528,9 +589,10 @@ export function expandWireEdit(wire: unknown): PlanEdit | unknown {
     return out;
 }
 
-/** An edit → the flat wire edit (what a model would write — fakes and specs write it). */
-export function planEditToWire(edit: PlanEdit): PlainObject {
-    const out: PlainObject = { op: edit.op, ...Object.fromEntries(Object.entries(EDIT_WIRE).map(([k, spec]) => [k, Array.isArray(spec.none) ? [] : spec.none])) };
+/** An edit's own keys → its flat wire edit, in its part's keys. */
+function flatEdit(edit: PlanEdit): PlainObject {
+    const part = PLAN_EDIT_OP_PART[edit.op];
+    const out: PlainObject = { op: edit.op, ...Object.fromEntries(planEditWireKeys(part).map(k => [k, Array.isArray(EDIT_WIRE[k].none) ? [] : EDIT_WIRE[k].none])) };
     for (const [planKey, wireKey] of Object.entries(PLAN_EDIT_WIRE_KEYS[edit.op])) {
         const value = (edit as unknown as PlainObject)[planKey];
         if (value === undefined) continue;
@@ -539,7 +601,26 @@ export function planEditToWire(edit: PlanEdit): PlainObject {
     return out;
 }
 
-/** A model's answer → edits (each flat edit expanded); never repaired. */
+/** The children an added page or content type travels without, as the edits that add them after it. */
+function childEdits(edit: PlanEdit): PlanEdit[] {
+    if (edit.op === PlanEditOp.AddPage) return edit.page.sections.map(section => ({ op: PlanEditOp.AddSection, page: edit.page.key, section }));
+    if (edit.op === PlanEditOp.AddContentType) return edit.contentType.fields.map(field => ({ op: PlanEditOp.AddField, contentType: edit.contentType.name, field }));
+    return [];
+}
+
+/** An edit → the flat wire edits a model would write for it: itself, then its children (fakes and specs write them). */
+export function planEditToWire(edit: PlanEdit): PlainObject[] {
+    return [flatEdit(edit), ...childEdits(edit).map(flatEdit)];
+}
+
+/** Edits → each part's flat wire edits, in order (what each part's answer would hold). */
+export function planEditsToWire(edits: ReadonlyArray<PlanEdit>): Record<PlanPart, PlainObject[]> {
+    const out = Object.fromEntries(PLAN_PARTS.map(part => [part, [] as PlainObject[]])) as Record<PlanPart, PlainObject[]>;
+    for (const edit of edits) out[PLAN_EDIT_OP_PART[edit.op]].push(...planEditToWire(edit));
+    return out;
+}
+
+/** A model's answer (either part's) → edits (each flat edit expanded); never repaired. */
 export function planEditsFromWire(answer: unknown): PlanEditsAnswer | unknown {
     if (!isPlainObject(answer) || !Array.isArray(answer['edits'])) return answer;
     return { ...answer, edits: (answer['edits'] as unknown[]).map(expandWireEdit) };

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

@@ -11,16 +11,21 @@ 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.
+ * 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 fixed.
+ * - **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 `/`).
@@ -31,13 +36,25 @@ import { isPlainObject, PlainObject, ShapeEntry, shapeKeys } from './shape-check
  * 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';
+/** 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',
-    Roles = 'roles',
+    RoleField = 'roleField',
     Field = 'field',
     Seed = 'seed',
     SeedValue = 'seedValue',
@@ -59,18 +76,24 @@ interface WireKey {
     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: 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: 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'),
@@ -79,17 +102,13 @@ const WIRE_KEYS: Readonly<Record<`${PlanWireEntry}`, Readonly<Record<string, Wir
     contentType: {
         name: key('contentType.name'),
         label: key('contentType.label'),
-        roles: key('contentType.roles'),
+        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' },
     },
-    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', "''"),
+    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'),
@@ -184,6 +203,25 @@ export const PLAN_WIRE_SHAPE: Readonly<Record<`${PlanWireEntry}`, ShapeEntry>> =
     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)));
@@ -220,13 +258,32 @@ 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);
+/** 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 shaped(PlanWireEntry.ContentType, {
+    return shapedAs(PlanWireEntry.ContentType, options, {
         name: jsonText(),
         label: jsonText(),
-        roles: shaped(PlanWireEntry.Roles, Object.fromEntries(roleKeys.map(k => [k, 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) }),
     });
@@ -260,8 +317,8 @@ export function wireSectionJsonSchema(): JsonSchema {
     });
 }
 
-export function wirePageJsonSchema(): JsonSchema {
-    return shaped(PlanWireEntry.Page, {
+export function wirePageJsonSchema(options: WireOptions = {}): JsonSchema {
+    return shapedAs(PlanWireEntry.Page, options, {
         key: jsonText(),
         name: jsonText(),
         route: jsonText(),
@@ -275,20 +332,32 @@ export function wirePageJsonSchema(): JsonSchema {
     });
 }
 
-/** 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 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(', ')}`);
-    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)),
-        }),
-    });
+    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 ────────────────────────────────────────────────────────────────────────────────────────────
@@ -329,10 +398,10 @@ export function expandWireField(wire: unknown): ContentFieldPlan | unknown {
     return { ...rest, ...optional('required', required, v => v === undefined || v === false), ...optional('note', note) };
 }
 
-export function expandWireContentType(wire: unknown): ContentTypePlan | unknown {
+export function expandWireContentType(wire: unknown, options: WireOptions = {}): 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) };
+    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;
@@ -365,9 +434,9 @@ export function expandWireSection(wire: unknown): PageSectionPlan | unknown {
     };
 }
 
-export function expandWirePage(wire: unknown): PagePlan | unknown {
+export function expandWirePage(wire: unknown, options: WireOptions = {}): PagePlan | unknown {
     if (!isPlainObject(wire)) return wire;
-    const { archetype, need, template, routeSource, seo, sections, ...rest } = 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,
@@ -387,12 +456,20 @@ function expandWireBusiness(wire: unknown, facts: PlanWireContext['facts']): unk
     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 (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`.
+ * 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(wire: unknown, context: PlanWireContext): SitePlan | unknown {
-    if (!isPlainObject(wire)) return wire;
+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,
@@ -413,11 +490,12 @@ 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]));
+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, fields: type.fields.map(fieldToWire),
+        name: type.name, label: type.label, roles, ...(options.children === false ? {} : { fields: type.fields.map(fieldToWire) }),
         seed: { count, sample, isPublished, values: mapToList(values, 'field', 'value') },
     };
 }
@@ -438,21 +516,29 @@ export function sectionToWire(section: PageSectionPlan): PlainObject {
     };
 }
 
-export function pageToWire(page: PagePlan): PlainObject {
+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 }, sections: page.sections.map(sectionToWire),
+        seo: { title: page.seo?.title ?? NONE, description: page.seo?.description ?? NONE },
+        ...(options.children === false ? {} : { 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 },
-    };
+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>;
 }