@vectoriox/iox-ui 5.59.1 → 5.61.0

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

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

package/src/generation-core/site-plan-schema.ts

@@ -1,252 +0,0 @@
-import { ANIMATE_IDS, DesignChoices } from '@vectoriox/iox-ui/design-core';
-import { FORM_PRESETS } from '@vectoriox/iox-ui/forms-core';
-
-import {
-    jsonAnyOf, jsonBoolean, jsonClosedObject, jsonInteger, jsonListOf, jsonOneOf, JsonSchema, jsonShapedObject, jsonText,
-} from './json-schema';
-import {
-    patternHasForm, patternLinkSlots, patternOptionalParts, patternSlots, patternTakesBinding, PatternGlobalPosition, SITE_PATTERNS, SitePattern,
-} from './patterns';
-import {
-    FACT_KEYS, GlobalSlot, PAGE_ARCHETYPES, SITE_NEED_IDS, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SitePlan, SitePlanSource, SitePlanSourceKind, SITE_LOCALES,
-    SITE_PLAN_VERSION,
-} from './site-plan.model';
-import { SPEC_SITE_PLAN_SHAPE } from './site-spec.generated';
-import { isPlainObject, PlainObject, ShapeEntry } from './shape-check';
-
-/**
- * The structured-output format a model writes a Site Plan in (AI plan §3d step 4, M1-3) — built from the SAME shape
- * table `validateSitePlan` reads (`SPEC_SITE_PLAN_SHAPE`) and the SAME pattern library, so the plan a model is told
- * about is the plan the gate refuses. ONE source: a key the table gains breaks this builder until it is written here.
- *
- * Two maps of the shape are written as LISTS on the wire, because no strict mode can say "any key": a section's
- * `slots` (`[{ slot, text }]`, the slot names closed per pattern) and a seed's field values (`values: [{ field,
- * value }]`). `sitePlanFromWire` turns them back; nothing else differs. Every section is one `anyOf` branch per
- * pattern — its id, its declared slots, its optional parts, a binding only when it takes one — and the design, the
- * source and the version are PINNED to the owner's pick and this run (one-value enums), so the provider cannot let
- * a model change the look. The gate still checks both (`plan.design` deep-equals the pick).
- */
-
-export const SITE_PLAN_SCHEMA_NAME = 'site_plan';
-
-/** The wire keys of the two maps written as lists. */
-export enum SitePlanWireKey {
-    SlotName = 'slot',
-    SlotText = 'text',
-    SeedValues = 'values',
-    SeedField = 'field',
-    SeedValue = 'value',
-}
-
-const SHAPE: Readonly<Record<string, ShapeEntry>> = SPEC_SITE_PLAN_SHAPE;
-
-export interface SitePlanSchemaPin {
-    /** The owner's pick, verbatim — every design key becomes a one-value enum. */
-    design: DesignChoices;
-    /** This generation. */
-    source: SitePlanSource;
-}
-
-const one = (value: string): JsonSchema => jsonOneOf([value]);
-const oneBoolean = (value: boolean): JsonSchema => ({ type: 'boolean', enum: [value] });
-
-/** The pick, key by key, as one-value enums; an optional key the pick leaves out may only be left out (or empty). */
-function pinnedDesign(design: DesignChoices): JsonSchema {
-    const entry = SHAPE['design'];
-    const values = design as unknown as Record<string, unknown>;
-    const properties: Record<string, JsonSchema> = {};
-    for (const key of Object.keys(entry).map(k => k.replace(/\?$/, ''))) {
-        const v = values[key];
-        if (typeof v === 'string') properties[key] = one(v);
-        else if (typeof v === 'boolean') properties[key] = oneBoolean(v);
-        else if (isPlainObject(v)) properties[key] = jsonClosedObject(
-            Object.fromEntries(Object.entries(v).map(([role, family]) => [role, one(String(family))])), Object.keys(v));
-        else properties[key] = jsonClosedObject({}, []);
-    }
-    const shaped = jsonShapedObject(entry, properties, 'design');
-    // Everything the pick carries is required: a model may not leave a choice out and let a default stand in.
-    const given = Object.keys(values).filter(k => values[k] !== undefined && k in properties);
-    return { ...shaped, required: [...new Set([...(shaped['required'] as string[]), ...given])] };
-}
-
-function sourceSchema(source: SitePlanSource): JsonSchema {
-    if (source.kind === SitePlanSourceKind.Ai) return jsonShapedObject(SHAPE['sourceAi'], { kind: one(source.kind), runId: one(source.runId) }, 'sourceAi');
-    return jsonShapedObject(SHAPE['sourceTemplate'], {
-        kind: one(source.kind), templateId: one(source.templateId), templateVersion: { type: 'integer', enum: [source.templateVersion] },
-    }, 'sourceTemplate');
-}
-
-function businessSchema(): JsonSchema {
-    const facts = jsonClosedObject(Object.fromEntries(FACT_KEYS.map(key => [key, jsonText()])), []);
-    return jsonShapedObject(SHAPE['business'], { name: jsonText(), tagline: jsonText(), facts }, 'business');
-}
-
-/** A content type's field. */
-export function fieldJsonSchema(): JsonSchema {
-    return jsonShapedObject(SHAPE['field'], { name: jsonText(), type: jsonText(), controller: jsonText(), required: jsonBoolean(), note: jsonText() }, 'field');
-}
-
-/** A content type, its seed's field values as a list (`values: [{ field, value }]`). */
-export function contentTypeJsonSchema(): JsonSchema {
-    const value = jsonAnyOf([jsonText(), jsonListOf(jsonText())]);
-    const values = jsonListOf(jsonClosedObject({ [SitePlanWireKey.SeedField]: jsonText(), [SitePlanWireKey.SeedValue]: value }, [SitePlanWireKey.SeedField, SitePlanWireKey.SeedValue]));
-    const seed = jsonShapedObject(SHAPE['seed'], { count: jsonInteger(), sample: jsonBoolean(), isPublished: jsonBoolean() }, 'seed',
-        { key: SitePlanWireKey.SeedValues, schema: values });
-    const roleKeys = Object.keys(SHAPE['roles']).map(k => k.replace(/\?$/, ''));
-    const roles = jsonShapedObject(SHAPE['roles'], Object.fromEntries(roleKeys.map(k => [k, jsonText()])), 'roles');
-    return jsonShapedObject(SHAPE['contentType'], {
-        name: jsonText(), label: jsonText(), roles, fields: jsonListOf(fieldJsonSchema()), seed,
-    }, 'contentType');
-}
-
-/** A data source: a cms list / single item, or a relative one. */
-export function dataSourceJsonSchema(): JsonSchema {
-    const byRoute = jsonClosedObject({ field: jsonText(), routeParam: jsonText() }, ['field', 'routeParam']);
-    const cms = jsonShapedObject(SHAPE['cmsDataSource'], {
-        alias: jsonText(), type: one(PlanDataSourceType.Cms), mode: jsonOneOf(Object.values(PlanDataSourceMode)),
-        contentType: jsonText(), limit: jsonInteger(), filterByRouteParam: byRoute,
-    }, 'cmsDataSource');
-    const relative = jsonShapedObject(SHAPE['relativeDataSource'], {
-        alias: jsonText(), type: one(PlanDataSourceType.Relative), of: jsonText(), op: jsonOneOf(Object.values(RelativeOp)), within: jsonText(),
-    }, 'relativeDataSource');
-    return jsonAnyOf([cms, relative]);
-}
-
-/** 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);
-}
-
-/** A key a pattern has nothing for: only `{}` (or leaving it out) — the decoder drops it. */
-const NOTHING = (): JsonSchema => jsonClosedObject({}, []);
-
-/** One section branch: this pattern's id, its declared slots (a list), the slots it may re-point (`links`, closed per
- *  pattern), its optional parts, a binding when it takes one, a form preset when it holds a form, its own entrance. */
-function sectionBranch(id: string, pattern: SitePattern): JsonSchema {
-    const slots = patternSlots(pattern);
-    const parts = patternOptionalParts(pattern);
-    const linkSlots = patternLinkSlots(pattern);
-    const slotList = slots.length
-        ? jsonListOf(jsonClosedObject({ [SitePlanWireKey.SlotName]: jsonOneOf(slots), [SitePlanWireKey.SlotText]: jsonText() }, [SitePlanWireKey.SlotName, SitePlanWireKey.SlotText]))
-        : NOTHING();
-    const branch = jsonShapedObject(SHAPE['section'], {
-        pattern: one(id),
-        slots: slotList,
-        links: linkSlots.length ? jsonClosedObject(Object.fromEntries(linkSlots.map(slot => [slot, jsonText()])), []) : NOTHING(),
-        binding: patternTakesBinding(pattern) ? jsonText() : NOTHING(),
-        without: parts.length ? jsonListOf(jsonOneOf(parts)) : NOTHING(),
-        form: patternHasForm(pattern) ? jsonOneOf(FORM_PRESETS.map(p => p.id)) : NOTHING(),
-        enter: jsonOneOf(ANIMATE_IDS),
-    }, 'section');
-    return { ...branch, description: `${id}: ${pattern.intent}` };
-}
-
-/** A page section: one branch per pattern. */
-export function sectionJsonSchema(): JsonSchema {
-    return jsonAnyOf(sectionPatternIds().map(id => sectionBranch(id, SITE_PATTERNS[id])));
-}
-
-/** A page. */
-export function pageJsonSchema(): JsonSchema {
-    const seo = jsonShapedObject(SHAPE['pageSeo'], { title: jsonText(), description: jsonText() }, 'pageSeo');
-    return jsonShapedObject(SHAPE['page'], {
-        key: jsonText(), name: jsonText(), route: jsonText(), isHome: jsonBoolean(), required: jsonBoolean(), inNav: jsonBoolean(),
-        archetype: jsonOneOf(Object.keys(PAGE_ARCHETYPES)), need: jsonOneOf(SITE_NEED_IDS), template: jsonText(), routeSource: jsonText(), seo, sections: jsonListOf(sectionJsonSchema()),
-    }, 'page');
-}
-
-const globalIds = (position: `${PatternGlobalPosition}`) => Object.entries(SITE_PATTERNS).filter(([, p]) => p.global === position).map(([id]) => id);
-
-/** The Site Plan format, pinned to the owner's pick and this run. */
-export function sitePlanJsonSchema(pin: SitePlanSchemaPin): JsonSchema {
-    const globals = jsonShapedObject(SHAPE['globals'], {
-        [GlobalSlot.Header]: jsonOneOf(globalIds(PatternGlobalPosition.Before)),
-        [GlobalSlot.Footer]: jsonOneOf(globalIds(PatternGlobalPosition.After)),
-    }, 'globals');
-    return jsonShapedObject(SHAPE['plan'], {
-        version: one(SITE_PLAN_VERSION),
-        source: sourceSchema(pin.source),
-        business: businessSchema(),
-        locale: jsonOneOf(Object.keys(SITE_LOCALES)),
-        design: pinnedDesign(pin.design),
-        contentTypes: jsonListOf(contentTypeJsonSchema()),
-        dataSources: jsonListOf(dataSourceJsonSchema()),
-        pages: jsonListOf(pageJsonSchema()),
-        globals,
-    }, 'plan');
-}
-
-// ── The wire → the plan ─────────────────────────────────────────────────────────────────────────────
-
-const isEmptyObject = (v: unknown) => isPlainObject(v) && Object.keys(v).length === 0;
-
-/** `[{ slot, text }]` → `{ slot: text }`; anything that is not that list is left for the gate to refuse. */
-function slotsFromWire(slots: unknown): unknown {
-    if (!Array.isArray(slots)) return slots;
-    const out: PlainObject = {};
-    for (const entry of slots) {
-        if (!isPlainObject(entry) || typeof entry[SitePlanWireKey.SlotName] !== 'string') return slots;
-        out[entry[SitePlanWireKey.SlotName] as string] = entry[SitePlanWireKey.SlotText];
-    }
-    return out;
-}
-
-/** A section off the wire: its slots back to a map; a key the pattern has nothing for (`{}`) dropped. */
-export function sectionFromWire(section: unknown): unknown {
-    if (!isPlainObject(section)) return section;
-    const out: PlainObject = { ...section };
-    for (const key of ['slots', 'links', 'binding', 'without', 'form']) if (isEmptyObject(out[key])) delete out[key];
-    if ('slots' in out) out['slots'] = slotsFromWire(out['slots']);
-    return out;
-}
-
-/** A content type off the wire: its seed's `values` list back to field keys. */
-export function contentTypeFromWire(type: unknown): unknown {
-    if (!isPlainObject(type) || !isPlainObject(type['seed'])) return type;
-    const { [SitePlanWireKey.SeedValues]: values, ...seed } = type['seed'] as PlainObject;
-    if (Array.isArray(values)) {
-        for (const entry of values) {
-            if (isPlainObject(entry) && typeof entry[SitePlanWireKey.SeedField] === 'string') seed[entry[SitePlanWireKey.SeedField] as string] = entry[SitePlanWireKey.SeedValue];
-        }
-    } else if (values !== undefined) seed[SitePlanWireKey.SeedValues] = values;
-    return { ...type, seed };
-}
-
-function pageFromWire(page: unknown): unknown {
-    if (!isPlainObject(page) || !Array.isArray(page['sections'])) return page;
-    return { ...page, sections: (page['sections'] as unknown[]).map(sectionFromWire) };
-}
-
-/** The design off the wire: an empty optional object (a choice the pick does not carry) dropped. */
-function designFromWire(design: unknown): unknown {
-    if (!isPlainObject(design)) return design;
-    return Object.fromEntries(Object.entries(design).filter(([, v]) => !isEmptyObject(v)));
-}
-
-/**
- * A model's answer → a Site Plan: the two listed maps back to maps, nothing else touched. Never repairs — whatever the
- * answer got wrong is still wrong, for `validateSitePlan` to refuse with a path.
- */
-export function sitePlanFromWire(wire: unknown): SitePlan | unknown {
-    if (!isPlainObject(wire)) return wire;
-    const out: PlainObject = { ...wire };
-    if (Array.isArray(out['contentTypes'])) out['contentTypes'] = (out['contentTypes'] as unknown[]).map(contentTypeFromWire);
-    if (Array.isArray(out['pages'])) out['pages'] = (out['pages'] as unknown[]).map(pageFromWire);
-    if ('design' in out) out['design'] = designFromWire(out['design']);
-    return out;
-}
-
-/** The plan → the wire (what a re-ask shows the model, and what the plan edits' prompt carries). */
-export function sitePlanToWire(plan: SitePlan): PlainObject {
-    const slotsToWire = (slots: Readonly<Record<string, string>> | undefined) =>
-        Object.entries(slots ?? {}).map(([slot, text]) => ({ [SitePlanWireKey.SlotName]: slot, [SitePlanWireKey.SlotText]: text }));
-    return {
-        ...plan,
-        contentTypes: plan.contentTypes.map(t => {
-            if (!t.seed) return t;
-            const { count, sample, isPublished, ...values } = t.seed;
-            return { ...t, seed: { count, sample, isPublished, [SitePlanWireKey.SeedValues]: Object.entries(values).map(([field, value]) => ({ [SitePlanWireKey.SeedField]: field, [SitePlanWireKey.SeedValue]: value })) } };
-        }),
-        pages: plan.pages.map(p => ({ ...p, sections: p.sections.map(s => (s.slots ? { ...s, slots: slotsToWire(s.slots) } : s)) })),
-    };
-}