@vectoriox/iox-ui 5.54.0 → 5.55.0

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

@@ -0,0 +1,428 @@
+import {
+    jsonAnyOf, jsonInteger, jsonListOf, jsonOneOf, JsonSchema, jsonShapedObject, jsonText,
+} from './json-schema';
+import { patternById, patternOptionalParts, patternSlots, patternTakesBinding } from './patterns';
+import {
+    contentTypeFromWire, contentTypeJsonSchema, dataSourceJsonSchema, fieldJsonSchema, pageJsonSchema, sectionFromWire, sectionJsonSchema,
+    sectionPatternIds,
+} from './site-plan-schema';
+import {
+    ContentFieldPlan, ContentTypePlan, DataSourcePlan, PagePlan, PageSectionPlan, PlanDataSourceMode, PlanDataSourceType, SitePlan,
+} from './site-plan.model';
+import { isNonEmptyString, isPlainObject, PathIssue, PathIssueCollector, PlainObject, ShapeEntry, shapeKeys } from './shape-check';
+
+/**
+ * Changing a plan by sentence (AI plan §3d "The Plan prompt box", M1-5; reused by M2 after a build): the CLOSED list
+ * of operations (N-D6) a model may write against the current plan, and the ONE pure `applyPlanEdits` that carries them
+ * out. Nothing is written until Build, so an edit is a plan → plan function; the result goes through
+ * `validateSitePlan` like any plan. Pages are named by `key`, sections by their index on the page. A set of edits is
+ * applied whole or not at all: one edit that cannot apply refuses the set, with a path, and the plan is unchanged.
+ */
+
+export enum PlanEditOp {
+    AddPage = 'addPage',
+    RemovePage = 'removePage',
+    RenamePage = 'renamePage',
+    MergePages = 'mergePages',
+    /** Its place in the menu (the plan's page order). */
+    MovePage = 'movePage',
+    AddSection = 'addSection',
+    RemoveSection = 'removeSection',
+    MoveSection = 'moveSection',
+    SwapPattern = 'swapPattern',
+    SetSlot = 'setSlot',
+    AddContentType = 'addContentType',
+    AddField = 'addField',
+    SetSectionData = 'setSectionData',
+}
+
+export type PlanEdit =
+    | { op: `${PlanEditOp.AddPage}`; page: PagePlan; after?: string }
+    | { op: `${PlanEditOp.RemovePage}`; page: string }
+    | { op: `${PlanEditOp.RenamePage}`; page: string; name?: string; route?: string }
+    | { op: `${PlanEditOp.MergePages}`; into: string; from: string }
+    | { op: `${PlanEditOp.MovePage}`; page: string; to: number }
+    | { op: `${PlanEditOp.AddSection}`; page: string; section: PageSectionPlan; at?: number }
+    | { op: `${PlanEditOp.RemoveSection}`; page: string; index: number }
+    | { op: `${PlanEditOp.MoveSection}`; page: string; from: number; to: number }
+    | { op: `${PlanEditOp.SwapPattern}`; page: string; index: number; pattern: string }
+    | { op: `${PlanEditOp.SetSlot}`; page: string; index: number; slot: string; text: string }
+    | { op: `${PlanEditOp.AddContentType}`; contentType: ContentTypePlan; dataSources?: DataSourcePlan[] }
+    | { op: `${PlanEditOp.AddField}`; contentType: string; field: ContentFieldPlan; sample?: string | string[] }
+    | { op: `${PlanEditOp.SetSectionData}`; page: string; index: number; binding: string };
+
+/**
+ * Every op's keys, explained — what the format is built from and what `validatePlanEdits` reads (`key?` optional).
+ * A page is named by its `key`; a section by its 0-based `index` on that page.
+ */
+export const PLAN_EDIT_SHAPE: Readonly<Record<`${PlanEditOp}`, ShapeEntry>> = {
+    [PlanEditOp.AddPage]: { op: "'addPage'", page: 'page — a whole new page (a unique key and route)', 'after?': 'string — the key of the page it follows in the menu; absent: last' },
+    [PlanEditOp.RemovePage]: { op: "'removePage'", page: 'string — the key of the page to remove (never the home page)' },
+    [PlanEditOp.RenamePage]: { op: "'renamePage'", page: 'string — a page key', 'name?': 'string — its new name (the menu label)', 'route?': 'string — its new route' },
+    [PlanEditOp.MergePages]: { op: "'mergePages'", into: 'string — the page that stays', from: 'string — the page whose sections move into it, then removed' },
+    [PlanEditOp.MovePage]: { op: "'movePage'", page: 'string — a page key', to: 'integer — its new 0-based place in the menu' },
+    [PlanEditOp.AddSection]: { op: "'addSection'", page: 'string — a page key', section: 'section', 'at?': 'integer — its 0-based place on the page; absent: last' },
+    [PlanEditOp.RemoveSection]: { op: "'removeSection'", page: 'string — a page key', index: 'integer — the section' },
+    [PlanEditOp.MoveSection]: { op: "'moveSection'", page: 'string — a page key', from: 'integer — the section', to: 'integer — its new place' },
+    [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.SetSectionData]: { op: "'setSectionData'", page: 'string — a page key', index: 'integer — the section', binding: 'string — the list source the section repeats' },
+};
+
+export enum PlanChangeKind {
+    Page = 'page',
+    Section = 'section',
+    ContentType = 'contentType',
+    Field = 'field',
+    DataSource = 'dataSource',
+}
+
+export enum PlanChangeAction {
+    Added = 'added',
+    Removed = 'removed',
+    Changed = 'changed',
+    Moved = 'moved',
+}
+
+/** What an edit changed — the Plan map marks it. `index` is the section's index in the RESULT (or before, when removed). */
+export interface PlanChange {
+    kind: `${PlanChangeKind}`;
+    action: `${PlanChangeAction}`;
+    page?: string;
+    index?: number;
+    name?: string;
+}
+
+export enum PlanEditIssueCode {
+    Shape = 'shape',
+    UnknownKey = 'unknown-key',
+    Duplicate = 'duplicate',
+    UnknownOp = 'unknown-op',
+    UnknownPage = 'unknown-page',
+    UnknownSection = 'unknown-section',
+    UnknownPattern = 'unknown-pattern',
+    UnknownSlot = 'unknown-slot',
+    UnknownContentType = 'unknown-content-type',
+    UnknownDataSource = 'unknown-data-source',
+    /** The home page stays (a plan has exactly one). */
+    HomePage = 'home-page',
+    /** A template page (one item per route) and a plain page cannot be merged. */
+    MergeTemplate = 'merge-template',
+}
+
+export type PlanEditIssue = PathIssue<PlanEditIssueCode>;
+
+export interface PlanEditResult {
+    plan: SitePlan;
+    changed: PlanChange[];
+    /** Non-empty: nothing was applied (`plan` is the input). */
+    issues: PlanEditIssue[];
+}
+
+class Collector extends PathIssueCollector<PlanEditIssueCode> {
+    constructor() {
+        super('plan edit', { shape: PlanEditIssueCode.Shape, unknownKey: PlanEditIssueCode.UnknownKey, duplicate: PlanEditIssueCode.Duplicate });
+    }
+}
+
+const OPS = Object.values(PlanEditOp) as string[];
+/** A page's own header section (`page-header.simple`) — what a merge leaves behind with the page it named. */
+const PAGE_HEADER_FAMILY = 'header';
+const clone = <T>(v: T): T => JSON.parse(JSON.stringify(v)) as T;
+const clamp = (n: number, max: number) => Math.max(0, Math.min(Math.trunc(n), max));
+
+/** The edits' structure: a known op, its keys (`PLAN_EDIT_SHAPE`), integers where an index is. Never repairs. */
+export function validatePlanEdits(edits: unknown): { valid: boolean; issues: PlanEditIssue[] } {
+    const c = new Collector();
+    if (!Array.isArray(edits)) {
+        c.add(PlanEditIssueCode.Shape, 'edits', 'must be an array');
+        return { valid: false, issues: c.issues };
+    }
+    edits.forEach((raw, i) => {
+        const path = `edits[${i}]`;
+        if (!isPlainObject(raw)) return c.add(PlanEditIssueCode.Shape, path, 'must be an object');
+        const op = raw['op'];
+        if (typeof op !== 'string' || !OPS.includes(op)) return c.add(PlanEditIssueCode.UnknownOp, `${path}.op`, `must be one of ${OPS.join(', ')}`);
+        const entry = PLAN_EDIT_SHAPE[op as PlanEditOp];
+        c.keys(raw, shapeKeys(entry), path);
+        for (const [key, text] of Object.entries(entry)) {
+            const optional = key.endsWith('?');
+            const name = optional ? key.slice(0, -1) : key;
+            const v = raw[name];
+            if (v === undefined) { if (!optional) c.add(PlanEditIssueCode.Shape, `${path}.${name}`, 'is required'); continue; }
+            if (text.startsWith('string | string[]')) {
+                if (typeof v !== 'string' && !(Array.isArray(v) && v.every(x => typeof x === 'string'))) c.add(PlanEditIssueCode.Shape, `${path}.${name}`, 'must be a string or a list of strings');
+            } else if (text.startsWith('string') && !isNonEmptyString(v)) c.add(PlanEditIssueCode.Shape, `${path}.${name}`, 'must be a non-empty string');
+            if (text.startsWith('integer') && !Number.isInteger(v)) c.add(PlanEditIssueCode.Shape, `${path}.${name}`, 'must be a whole number');
+            if (['page', 'section', 'contentType', 'field'].includes(text.split(' ')[0]) && !isPlainObject(v)) c.add(PlanEditIssueCode.Shape, `${path}.${name}`, 'must be an object');
+            if (text.startsWith('dataSource[]') && !Array.isArray(v)) c.add(PlanEditIssueCode.Shape, `${path}.${name}`, 'must be an array');
+        }
+    });
+    return { valid: c.issues.length === 0, issues: c.issues };
+}
+
+/** The aliases a page reads (its route source and its sections' bindings). */
+function aliasesOf(pages: ReadonlyArray<PagePlan>): Set<string> {
+    const out = new Set<string>();
+    for (const page of pages) {
+        if (page.routeSource) out.add(page.routeSource);
+        for (const s of page.sections) if (s.binding) out.add(s.binding);
+    }
+    return out;
+}
+
+/** A relative source (`project.next`'s) is read while its subject is, and keeps the list it walks. */
+function withDependencies(aliases: Set<string>, sources: ReadonlyArray<DataSourcePlan>): Set<string> {
+    const out = new Set(aliases);
+    for (const s of sources) {
+        if (s.type === PlanDataSourceType.Relative && aliases.has(s.of)) { out.add(s.alias); out.add(s.within); }
+    }
+    return out;
+}
+
+interface Draft {
+    pages: PagePlan[];
+    contentTypes: ContentTypePlan[];
+    dataSources: DataSourcePlan[];
+}
+
+type Apply = (d: Draft, e: any, c: Collector, path: string, changed: PlanChange[]) => void;
+
+const pageIndex = (d: Draft, key: unknown) => d.pages.findIndex(p => p.key === key);
+
+function findPage(d: Draft, key: unknown, c: Collector, path: string): number {
+    const at = pageIndex(d, key);
+    if (at < 0) c.add(PlanEditIssueCode.UnknownPage, path, `no page "${String(key)}" in the plan (${d.pages.map(p => p.key).join(', ')})`);
+    return at;
+}
+
+function findSection(d: Draft, pageAt: number, index: unknown, c: Collector, path: string): boolean {
+    const ok = Number.isInteger(index) && (index as number) >= 0 && (index as number) < d.pages[pageAt].sections.length;
+    if (!ok) c.add(PlanEditIssueCode.UnknownSection, path, `page "${d.pages[pageAt].key}" has sections 0–${d.pages[pageAt].sections.length - 1}`);
+    return ok;
+}
+
+const setSections = (d: Draft, at: number, sections: PageSectionPlan[]) => { d.pages[at] = { ...d.pages[at], sections }; };
+
+/** One handler per op — a data table, never an if-chain. */
+const APPLY: Readonly<Record<`${PlanEditOp}`, Apply>> = {
+    [PlanEditOp.AddPage]: (d, e, c, path, changed) => {
+        const page = { ...(e.page as PagePlan), sections: (e.page.sections ?? []).map(sectionFromWire) } as PagePlan;
+        if (pageIndex(d, page.key) >= 0) return c.add(PlanEditIssueCode.Duplicate, `${path}.page.key`, `page "${page.key}" is already in the plan`);
+        const after = e.after === undefined ? d.pages.length - 1 : findPage(d, e.after, c, `${path}.after`);
+        if (after < 0 && e.after !== undefined) return;
+        d.pages.splice(after + 1, 0, page);
+        changed.push({ kind: PlanChangeKind.Page, action: PlanChangeAction.Added, page: page.key, name: page.name });
+    },
+    [PlanEditOp.RemovePage]: (d, e, c, path, changed) => {
+        const at = findPage(d, e.page, c, `${path}.page`);
+        if (at < 0) return;
+        if (d.pages[at].isHome) return c.add(PlanEditIssueCode.HomePage, `${path}.page`, 'the home page stays — rename or change it instead');
+        const [gone] = d.pages.splice(at, 1);
+        changed.push({ kind: PlanChangeKind.Page, action: PlanChangeAction.Removed, page: gone.key, name: gone.name });
+    },
+    [PlanEditOp.RenamePage]: (d, e, c, path, changed) => {
+        const at = findPage(d, e.page, c, `${path}.page`);
+        if (at < 0) return;
+        d.pages[at] = { ...d.pages[at], ...(e.name !== undefined ? { name: e.name } : {}), ...(e.route !== undefined ? { route: e.route } : {}) };
+        changed.push({ kind: PlanChangeKind.Page, action: PlanChangeAction.Changed, page: d.pages[at].key, name: d.pages[at].name });
+    },
+    [PlanEditOp.MergePages]: (d, e, c, path, changed) => {
+        const into = findPage(d, e.into, c, `${path}.into`);
+        const from = findPage(d, e.from, c, `${path}.from`);
+        if (into < 0 || from < 0) return;
+        if (into === from) return c.add(PlanEditIssueCode.Duplicate, `${path}.from`, 'a page is merged into another page');
+        const a = d.pages[into];
+        const b = d.pages[from];
+        if (!!a.template !== !!b.template) return c.add(PlanEditIssueCode.MergeTemplate, `${path}.from`, 'a page per item and a plain page cannot be merged');
+        if (b.isHome) return c.add(PlanEditIssueCode.HomePage, `${path}.from`, 'the home page stays — merge the other page into it');
+        const moved = b.sections.filter((s, i) => !(i === 0 && patternById(s.pattern)?.family === PAGE_HEADER_FAMILY));
+        setSections(d, into, [...a.sections, ...moved]);
+        moved.forEach((_, k) => changed.push({ kind: PlanChangeKind.Section, action: PlanChangeAction.Added, page: a.key, index: a.sections.length + k }));
+        d.pages.splice(from, 1);
+        changed.push({ kind: PlanChangeKind.Page, action: PlanChangeAction.Changed, page: a.key, name: a.name });
+        changed.push({ kind: PlanChangeKind.Page, action: PlanChangeAction.Removed, page: b.key, name: b.name });
+    },
+    [PlanEditOp.MovePage]: (d, e, c, path, changed) => {
+        const at = findPage(d, e.page, c, `${path}.page`);
+        if (at < 0) return;
+        const [page] = d.pages.splice(at, 1);
+        d.pages.splice(clamp(e.to, d.pages.length), 0, page);
+        changed.push({ kind: PlanChangeKind.Page, action: PlanChangeAction.Moved, page: page.key, name: page.name });
+    },
+    [PlanEditOp.AddSection]: (d, e, c, path, changed) => {
+        const at = findPage(d, e.page, c, `${path}.page`);
+        if (at < 0) return;
+        const sections = [...d.pages[at].sections];
+        const index = e.at === undefined ? sections.length : clamp(e.at, sections.length);
+        sections.splice(index, 0, sectionFromWire(e.section) as PageSectionPlan);
+        setSections(d, at, sections);
+        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`);
+        if (at < 0 || !findSection(d, at, e.index, c, `${path}.index`)) return;
+        setSections(d, at, d.pages[at].sections.filter((_, i) => i !== e.index));
+        changed.push({ kind: PlanChangeKind.Section, action: PlanChangeAction.Removed, page: d.pages[at].key, index: e.index });
+    },
+    [PlanEditOp.MoveSection]: (d, e, c, path, changed) => {
+        const at = findPage(d, e.page, c, `${path}.page`);
+        if (at < 0 || !findSection(d, at, e.from, c, `${path}.from`)) return;
+        const sections = [...d.pages[at].sections];
+        const [section] = sections.splice(e.from, 1);
+        const to = clamp(e.to, sections.length);
+        sections.splice(to, 0, section);
+        setSections(d, at, sections);
+        changed.push({ kind: PlanChangeKind.Section, action: PlanChangeAction.Moved, page: d.pages[at].key, index: to });
+    },
+    [PlanEditOp.SwapPattern]: (d, e, c, path, changed) => {
+        const at = findPage(d, e.page, c, `${path}.page`);
+        if (at < 0 || !findSection(d, at, e.index, c, `${path}.index`)) return;
+        const next = patternById(e.pattern);
+        if (!next || next.global) return c.add(PlanEditIssueCode.UnknownPattern, `${path}.pattern`, `no section pattern "${String(e.pattern)}"`);
+        const old = d.pages[at].sections[e.index];
+        const slots = Object.fromEntries(Object.entries(old.slots ?? {}).filter(([slot]) => patternSlots(next).includes(slot)));
+        const without = (old.without ?? []).filter(w => patternOptionalParts(next).includes(w));
+        const section: PageSectionPlan = {
+            pattern: e.pattern,
+            ...(Object.keys(slots).length ? { slots } : {}),
+            ...(old.binding && patternTakesBinding(next) ? { binding: old.binding } : {}),
+            ...(without.length ? { without } : {}),
+        };
+        setSections(d, at, d.pages[at].sections.map((s, i) => (i === e.index ? section : s)));
+        changed.push({ kind: PlanChangeKind.Section, action: PlanChangeAction.Changed, page: d.pages[at].key, index: e.index });
+    },
+    [PlanEditOp.SetSlot]: (d, e, c, path, changed) => {
+        const at = findPage(d, e.page, c, `${path}.page`);
+        if (at < 0 || !findSection(d, at, e.index, c, `${path}.index`)) return;
+        const section = d.pages[at].sections[e.index];
+        const declared = patternSlots(patternById(section.pattern)!);
+        if (!declared.includes(e.slot)) return c.add(PlanEditIssueCode.UnknownSlot, `${path}.slot`, `"${section.pattern}" has no slot "${e.slot}" (${declared.join(', ') || 'none'})`);
+        setSections(d, at, d.pages[at].sections.map((s, i) => (i === e.index ? { ...s, slots: { ...(s.slots ?? {}), [e.slot]: e.text } } : s)));
+        changed.push({ kind: PlanChangeKind.Section, action: PlanChangeAction.Changed, page: d.pages[at].key, index: e.index });
+    },
+    [PlanEditOp.AddContentType]: (d, e, c, path, changed) => {
+        const type = contentTypeFromWire(e.contentType) as ContentTypePlan;
+        if (d.contentTypes.some(t => t.name === type.name)) return c.add(PlanEditIssueCode.Duplicate, `${path}.contentType.name`, `content type "${type.name}" is already in the plan`);
+        d.contentTypes.push(type);
+        changed.push({ kind: PlanChangeKind.ContentType, action: PlanChangeAction.Added, name: type.name });
+        for (const [k, source] of ((e.dataSources ?? []) as DataSourcePlan[]).entries()) {
+            if (d.dataSources.some(s => s.alias === source.alias)) { c.add(PlanEditIssueCode.Duplicate, `${path}.dataSources[${k}].alias`, `data source "${source.alias}" is already in the plan`); continue; }
+            d.dataSources.push(source);
+            changed.push({ kind: PlanChangeKind.DataSource, action: PlanChangeAction.Added, name: source.alias });
+        }
+    },
+    [PlanEditOp.AddField]: (d, e, c, path, changed) => {
+        const at = d.contentTypes.findIndex(t => t.name === e.contentType);
+        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;
+        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}` });
+    },
+    [PlanEditOp.SetSectionData]: (d, e, c, path, changed) => {
+        const at = findPage(d, e.page, c, `${path}.page`);
+        if (at < 0 || !findSection(d, at, e.index, c, `${path}.index`)) return;
+        const source = d.dataSources.find(s => s.alias === e.binding);
+        if (!source || source.type !== PlanDataSourceType.Cms || source.mode !== PlanDataSourceMode.Query) {
+            return c.add(PlanEditIssueCode.UnknownDataSource, `${path}.binding`, `no list source "${String(e.binding)}" in the plan`);
+        }
+        setSections(d, at, d.pages[at].sections.map((s, i) => (i === e.index ? { ...s, binding: e.binding } : s)));
+        changed.push({ kind: PlanChangeKind.Section, action: PlanChangeAction.Changed, page: d.pages[at].key, index: e.index });
+    },
+};
+
+/**
+ * Apply a set of edits to a plan — all of them, or none (any issue refuses the set and returns the plan unchanged). The
+ * sources only removed pages and sections read are dropped with them; sources nothing read before are kept.
+ * The result still has to pass `validateSitePlan`.
+ */
+export function applyPlanEdits(plan: SitePlan, edits: ReadonlyArray<PlanEdit>): PlanEditResult {
+    const structure = validatePlanEdits(edits);
+    if (!structure.valid) return { plan, changed: [], issues: structure.issues };
+    const draft: Draft = { pages: clone([...plan.pages]), contentTypes: clone([...plan.contentTypes]), dataSources: clone([...plan.dataSources]) };
+    const c = new Collector();
+    const changed: PlanChange[] = [];
+    edits.forEach((edit, i) => APPLY[edit.op](draft, edit, c, `edits[${i}]`, changed));
+    if (c.issues.length) return { plan, changed: [], issues: c.issues };
+
+    const before = withDependencies(aliasesOf(plan.pages), plan.dataSources);
+    const after = withDependencies(aliasesOf(draft.pages), draft.dataSources);
+    const added = new Set(changed.filter(ch => ch.kind === PlanChangeKind.DataSource).map(ch => ch.name));
+    const dataSources = draft.dataSources.filter(s => after.has(s.alias) || !before.has(s.alias) || added.has(s.alias));
+    for (const s of draft.dataSources) if (!dataSources.includes(s)) changed.push({ kind: PlanChangeKind.DataSource, action: PlanChangeAction.Removed, name: s.alias });
+
+    return { plan: { ...plan, pages: draft.pages, contentTypes: draft.contentTypes, dataSources }, changed, issues: [] };
+}
+
+// ── The format a model writes edits in ─────────────────────────────────────────────────────────────────
+
+export const PLAN_EDITS_SCHEMA_NAME = 'plan_edits';
+
+/** A sentence's answer: the edits, or why the ops cannot say it (one line, in the owner's language). */
+export enum PlanEditsOutcome {
+    Edits = 'edits',
+    Cannot = 'cannot',
+}
+
+export interface PlanEditsAnswer {
+    outcome: `${PlanEditsOutcome}`;
+    edits: PlanEdit[];
+    /** `cannot`: the one line the owner reads. `edits`: empty. */
+    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 ''",
+};
+
+const one = (value: string): JsonSchema => jsonOneOf([value]);
+
+/** The schema of each op's value types (what `PLAN_EDIT_SHAPE` names). */
+function opSchema(op: `${PlanEditOp}`): JsonSchema {
+    const entry = PLAN_EDIT_SHAPE[op];
+    const valueOf = (key: string): JsonSchema => {
+        const text = entry[key] ?? entry[`${key}?`];
+        if (key === 'op') return one(op);
+        if (key === 'pattern') return jsonOneOf(sectionPatternIds());
+        const head = text.split(' ')[0];
+        const table: Record<string, () => JsonSchema> = {
+            page: pageJsonSchema, section: sectionJsonSchema, contentType: contentTypeJsonSchema, field: fieldJsonSchema,
+            'dataSource[]': () => jsonListOf(dataSourceJsonSchema()), integer: jsonInteger, string: jsonText,
+        };
+        if (text.startsWith('string | string[]')) return jsonAnyOf([jsonText(), jsonListOf(jsonText())]);
+        return (table[head] ?? jsonText)();
+    };
+    return jsonShapedObject(entry, Object.fromEntries(shapeKeys(entry).map(key => [key, valueOf(key)])), op);
+}
+
+/** The format a sentence's answer is written in: the outcome, the edits (one `anyOf` branch per op), the reason. */
+export function planEditsJsonSchema(): JsonSchema {
+    return jsonShapedObject(PLAN_EDITS_ANSWER_SHAPE, {
+        outcome: jsonOneOf(Object.values(PlanEditsOutcome)),
+        edits: jsonListOf(jsonAnyOf(OPS.map(op => opSchema(op as PlanEditOp)))),
+        reason: jsonText(),
+    }, 'planEdits');
+}
+
+/** A model's answer → edits (sections and content types off the wire); never repaired. */
+export function planEditsFromWire(answer: unknown): PlanEditsAnswer | unknown {
+    if (!isPlainObject(answer) || !Array.isArray(answer['edits'])) return answer;
+    const edits = (answer['edits'] as unknown[]).map(raw => {
+        if (!isPlainObject(raw)) return raw;
+        const e: PlainObject = { ...raw };
+        if (isPlainObject(e['page']) && Array.isArray((e['page'] as PlainObject)['sections'])) {
+            e['page'] = { ...(e['page'] as PlainObject), sections: ((e['page'] as PlainObject)['sections'] as unknown[]).map(sectionFromWire) };
+        }
+        if (isPlainObject(e['section'])) e['section'] = sectionFromWire(e['section']);
+        if (isPlainObject(e['contentType'])) e['contentType'] = contentTypeFromWire(e['contentType']);
+        return e;
+    });
+    return { ...answer, edits };
+}

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

@@ -0,0 +1,114 @@
+import { PathIssue } from './shape-check';
+import { FACT_KEYS, FactKey, SitePlan } from './site-plan.model';
+
+/**
+ * The plan stage's word checks (AI plan §3d / §3h, M1-3): every text a model WROTE into a plan — the tagline, page
+ * names, section slots, content-type labels, sample values — scanned for the words the owner and their kind of
+ * business must not use (`avoidWords`, the analysis's + the type's `words`), and for a fact the owner never gave
+ * (an email, phone number, price or opening time that is not one of the owner's own facts). A finding is a refusal
+ * with a path — the model rewrites; nothing here repairs a word. Pure.
+ */
+
+export enum PlanWordIssueCode {
+    /** A word the owner (or their kind of business) must not use. */
+    AvoidWord = 'avoid-word',
+    /** Something that looks like a fact — an email, phone, price or time — that is not one of the owner's facts. */
+    InventedFact = 'invented-fact',
+    /** `business.facts` holds a fact the owner did not give, or not in the owner's words. */
+    FactNotTheOwners = 'fact-not-the-owners',
+}
+
+export type PlanWordIssue = PathIssue<PlanWordIssueCode>;
+
+export interface PlanWordContext {
+    avoidWords: ReadonlyArray<string>;
+    /** The owner's own facts (the analysis's, as corrected) — the only ones a plan may carry. */
+    facts: Readonly<Partial<Record<FactKey, string>>>;
+}
+
+/** A text a model wrote, and where. */
+export interface WrittenText {
+    path: string;
+    text: string;
+}
+
+/** Every text in a plan a model writes (never ids, routes, field names or pattern ids). */
+export function writtenTexts(plan: SitePlan): WrittenText[] {
+    const out: WrittenText[] = [];
+    const add = (path: string, text: unknown) => { if (typeof text === 'string' && text.trim()) out.push({ path, text }); };
+    add('business.tagline', plan.business?.tagline);
+    plan.pages?.forEach((page, p) => {
+        add(`pages[${p}].name`, page.name);
+        page.sections?.forEach((section, s) => {
+            for (const [slot, text] of Object.entries(section.slots ?? {})) add(`pages[${p}].sections[${s}].slots.${slot}`, text);
+        });
+    });
+    plan.contentTypes?.forEach((type, t) => {
+        add(`contentTypes[${t}].label`, type.label);
+        for (const [field, value] of Object.entries(type.seed ?? {})) {
+            const values = Array.isArray(value) ? value : [value];
+            values.forEach((v, k) => add(`contentTypes[${t}].seed.${field}${Array.isArray(value) ? `[${k}]` : ''}`, v));
+        }
+    });
+    return out;
+}
+
+const HEBREW = /[֐-׿]/;
+/** Hebrew joins up to two one-letter words (and, the, in, to, from, that, as) to the next: "והטוב" holds "טוב". */
+const HEBREW_PREFIXES = '[והבלמשכ]{0,2}';
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const normalise = (s: string) => s.normalize('NFKC').toLowerCase();
+
+/** A word (or phrase) as a whole-word pattern; Hebrew allows its one-letter prefixes. */
+export function wordPattern(word: string): RegExp {
+    const w = escape(normalise(word.trim())).replace(/\s+/g, '\\s+');
+    const prefix = HEBREW.test(word) ? HEBREW_PREFIXES : '';
+    return new RegExp(`(?<![\\p{L}\\p{N}])${prefix}${w}(?![\\p{L}\\p{N}])`, 'u');
+}
+
+/** What a fact looks like when a model writes one — each judged against the owner's facts. */
+const FACT_SHAPES: ReadonlyArray<{ kind: string; pattern: RegExp; key: (match: string) => string }> = [
+    { kind: 'email', pattern: /[\p{L}\p{N}._%+-]+@[\p{L}\p{N}-]+(?:\.[\p{L}\p{N}-]+)+/gu, key: m => m.toLowerCase() },
+    { kind: 'phone', pattern: /\+?\d[\d\s().-]{6,}\d/g, key: m => m.replace(/\D/g, '') },
+    { kind: 'price', pattern: /(?:[$€£₪]\s?\d[\d,.]*|\d[\d,.]*\s?(?:[$€£₪]|ש"ח|NIS|USD|EUR|GBP))/gu, key: m => m.replace(/[^\d]/g, '') },
+    { kind: 'time', pattern: /(?<!\d)\d{1,2}[:.]\d{2}(?!\d)/g, key: m => m.replace(/\D/g, '') },
+];
+
+const MIN_PHONE_DIGITS = 8;
+/** "2019 – 2024" is two years, not a phone number. */
+const YEAR_RANGE = /^\s*\d{4}\s*[-–]\s*\d{4}\s*$/;
+
+function ownedKeys(facts: PlanWordContext['facts']): Set<string> {
+    const keys = new Set<string>();
+    for (const value of Object.values(facts)) {
+        if (typeof value !== 'string') continue;
+        for (const shape of FACT_SHAPES) for (const m of value.match(shape.pattern) ?? []) keys.add(`${shape.kind}:${shape.key(m)}`);
+    }
+    return keys;
+}
+
+/** The words to avoid and the facts never given, in every written text of the plan. */
+export function planWordIssues(plan: SitePlan, ctx: PlanWordContext): PlanWordIssue[] {
+    const issues: PlanWordIssue[] = [];
+    const avoid = [...new Set(ctx.avoidWords.map(w => w.trim()).filter(Boolean))].map(w => ({ word: w, pattern: wordPattern(w) }));
+    const owned = ownedKeys(ctx.facts);
+    for (const { path, text } of writtenTexts(plan)) {
+        const words = normalise(text);
+        for (const a of avoid) if (a.pattern.test(words)) issues.push({ code: PlanWordIssueCode.AvoidWord, path, message: `uses "${a.word}" — a word this site must not use` });
+        for (const shape of FACT_SHAPES) {
+            for (const m of text.match(shape.pattern) ?? []) {
+                const key = shape.key(m);
+                if (shape.kind === 'phone' && (key.length < MIN_PHONE_DIGITS || YEAR_RANGE.test(m))) continue;
+                if (!owned.has(`${shape.kind}:${key}`)) issues.push({ code: PlanWordIssueCode.InventedFact, path, message: `"${m.trim()}" looks like a ${shape.kind} the owner never gave — leave it out` });
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(plan.business?.facts ?? {})) {
+        const own = ctx.facts[key as FactKey];
+        if (!(FACT_KEYS as ReadonlyArray<string>).includes(key)) continue;
+        if (typeof own !== 'string' || normalise(own).trim() !== normalise(String(value)).trim()) {
+            issues.push({ code: PlanWordIssueCode.FactNotTheOwners, path: `business.facts.${key}`, message: own ? `must be the owner's own words: "${own}"` : 'the owner did not give it — leave it out (it becomes a placeholder)' });
+        }
+    }
+    return issues;
+}

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

@@ -18,6 +18,7 @@ export * from './patterns';
 export * from './templates';
 export * from './serialized-node';
 export * from './shape-check';
+export * from './json-schema';
 export * from './validate-site-plan';
 export * from './compose-site';
 export * from './nav-shape';
@@ -25,3 +26,6 @@ export * from './entrances';
 export * from './plan-data';
 export * from './site-build-run';
 export * from './ai-run';
+export * from './site-plan-schema';
+export * from './plan-edits';
+export * from './plan-words';