@urbicon-ui/blocks 6.38.0 → 6.40.1

package/dist/components/Chat/A2UIView/a2ui-validate.js

@@ -0,0 +1,773 @@
+/**
+ * The A2UI processor: incremental, whitelist-only, fail-loud validation that
+ * turns a stream of Server→Client envelopes into per-surface component maps and
+ * data models. Pure TS, no Svelte — deliberately NOT reactive (the house
+ * pattern of the streaming-markdown engine: plain Maps mutated in place; the
+ * Svelte layer bumps a version counter to re-derive the render tree).
+ *
+ * Security posture (untrusted-payload path):
+ * - Whitelist-only: only registry-declared props reach the render layer, so
+ *   handler injection (`onclick`, …) and prop smuggling are structurally
+ *   impossible — there is no payload spread.
+ * - `__proto__`/`constructor`/`prototype` are rejected as component ids, prop
+ *   keys, pointer segments and action-context keys.
+ * - Never merges or spreads payload objects; everything flows through `Map`s.
+ * - `collectGraphIssues` bounds traversal (depth 32, nodes 512) to cap DoS.
+ *
+ * Issue routing: envelope-level faults (bad version, unknown envelope type,
+ * op-before-createSurface) land in `globalIssues`; everything scoped to a known
+ * surface lands in that surface's `issues`. Graph-level faults (cycle, depth,
+ * node count, dangling refs) are computed on demand by `collectGraphIssues`,
+ * because "dangling" is a warning mid-stream and an error once settled.
+ */
+import { A2UI_ISSUE_CODES } from './a2ui.types.js';
+import { cloneData, deleteAtPointer, getAtPointer, setAtPointer } from './a2ui-data.js';
+import { A2UI_ICON_NAMES, A2UI_IGNORED_PROPS, A2UI_REGISTRY, A2UI_SUPPORTED_VERSIONS, A2UI_SVG_PATH_RE, UNSUPPORTED_A2UI_COMPONENTS } from './a2ui-registry.js';
+const PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+// DoS caps. The per-surface render walk is already bounded (depth 32, nodes
+// 512), but that leaves the *number* of surfaces and the per-message component
+// count unbounded — an attacker-streamed flood of tiny createSurface pairs (the
+// render tree re-derives every surface on each version bump) or one giant
+// updateComponents array would otherwise pin the main thread. Capping surface
+// count keeps the whole-processor re-derive O(surfaces·nodes) with a constant,
+// and capping the component list bounds each message's validation work.
+const MAX_SURFACES = 64;
+const MAX_COMPONENTS_PER_UPDATE = 1024;
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isContainer(value) {
+    return value !== null && typeof value === 'object';
+}
+function issue(severity, code, message, extra) {
+    return { severity, code, message, ...extra };
+}
+const OP_KEYS = ['createSurface', 'updateComponents', 'updateDataModel', 'deleteSurface'];
+// ── Dynamic-value shape guards ───────────────────────────────────────────────
+function isDataBinding(value) {
+    return isPlainObject(value) && typeof value.path === 'string';
+}
+function isFunctionCall(value) {
+    return isPlainObject(value) && typeof value.call === 'string';
+}
+function isDynamicRef(value) {
+    return isDataBinding(value) || isFunctionCall(value);
+}
+function isDynamicString(value) {
+    return typeof value === 'string' || isDynamicRef(value);
+}
+function isDynamicNumber(value) {
+    return (typeof value === 'number' && Number.isFinite(value)) || isDynamicRef(value);
+}
+function isDynamicBoolean(value) {
+    return typeof value === 'boolean' || isDynamicRef(value);
+}
+function isDynamicStringList(value) {
+    return ((Array.isArray(value) && value.every((item) => typeof item === 'string')) || isDynamicRef(value));
+}
+/**
+ * Faults that only a dynamic *reference* value can carry, surfaced at validation
+ * time so they reach `onValidationError` (the render layer resolves with only
+ * `.value` and drops the issue — this is the closed feedback loop the agent
+ * needs). A function-call binding is unsupported (renders to nothing → warning);
+ * a `{ path }` binding whose pointer contains a prototype-pollution segment is a
+ * hard error (position-independent, so scope need not be resolved here). Plain
+ * literals return no issues.
+ */
+function dynamicRefIssues(value, path, surfaceId) {
+    if (isFunctionCall(value)) {
+        const call = value.call;
+        return [
+            issue('warning', A2UI_ISSUE_CODES.FUNCTION_CALL_UNSUPPORTED, `Function-call binding "${String(call)}" is not supported; it resolves to nothing`, { surfaceId, path })
+        ];
+    }
+    if (isDataBinding(value)) {
+        const raw = value.path;
+        const tokens = (raw.startsWith('/') ? raw.slice(1) : raw).split('/');
+        for (const token of tokens) {
+            const segment = token.replaceAll('~1', '/').replaceAll('~0', '~');
+            if (PROTO_KEYS.has(segment)) {
+                return [
+                    issue('error', A2UI_ISSUE_CODES.PROTOTYPE_POLLUTION, `Prohibited property name "${segment}" in binding path "${raw}"`, { surfaceId, path })
+                ];
+            }
+        }
+    }
+    return [];
+}
+function validateProp(componentName, key, spec, value, path, surfaceId) {
+    const issues = [];
+    const mismatch = (detail) => {
+        issues.push(issue('error', A2UI_ISSUE_CODES.TYPE_MISMATCH, detail, { surfaceId, path }));
+        return { store: false, issues };
+    };
+    switch (spec.kind) {
+        case 'string':
+            if (spec.dynamic ? isDynamicString(value) : typeof value === 'string')
+                return { store: true, issues: dynamicRefIssues(value, path, surfaceId) };
+            return mismatch(`"${key}" on ${componentName} must be a string${spec.dynamic ? ' or { path } binding' : ''}`);
+        case 'number':
+            if (spec.dynamic ? isDynamicNumber(value) : typeof value === 'number' && Number.isFinite(value))
+                return { store: true, issues: dynamicRefIssues(value, path, surfaceId) };
+            return mismatch(`"${key}" on ${componentName} must be a finite number${spec.dynamic ? ' or { path } binding' : ''}`);
+        case 'boolean':
+            if (spec.dynamic ? isDynamicBoolean(value) : typeof value === 'boolean')
+                return { store: true, issues: dynamicRefIssues(value, path, surfaceId) };
+            return mismatch(`"${key}" on ${componentName} must be a boolean${spec.dynamic ? ' or { path } binding' : ''}`);
+        case 'stringList':
+            if (isDynamicStringList(value))
+                return { store: true, issues: dynamicRefIssues(value, path, surfaceId) };
+            return mismatch(`"${key}" on ${componentName} must be a string array or { path } binding`);
+        case 'enum':
+            if (typeof value === 'string' && spec.values?.includes(value))
+                return { store: true, issues };
+            issues.push(issue('error', A2UI_ISSUE_CODES.UNKNOWN_ENUM, `"${key}" on ${componentName} must be one of: ${(spec.values ?? []).join(', ')}`, { surfaceId, path }));
+            return { store: false, issues };
+        case 'childId':
+            if (typeof value === 'string')
+                return { store: true, issues };
+            return mismatch(`"${key}" on ${componentName} must be a component id (string)`);
+        case 'childList':
+            return validateChildList(componentName, key, value, path, surfaceId);
+        case 'action':
+            return validateAction(componentName, key, value, path, surfaceId);
+        case 'options':
+            return validateOptions(componentName, key, value, path, surfaceId);
+        case 'icon':
+            return validateIcon(value, path, surfaceId);
+        case 'accessibility':
+            if (isPlainObject(value))
+                return { store: true, issues };
+            return mismatch(`"${key}" on ${componentName} must be an object { label?, description? }`);
+    }
+}
+function validateChildList(componentName, key, value, path, surfaceId) {
+    if (Array.isArray(value)) {
+        if (value.every((item) => typeof item === 'string'))
+            return { store: true, issues: [] };
+        return {
+            store: false,
+            issues: [
+                issue('error', A2UI_ISSUE_CODES.TYPE_MISMATCH, `"${key}" on ${componentName} must be an array of component ids`, {
+                    surfaceId,
+                    path
+                })
+            ]
+        };
+    }
+    if (isPlainObject(value) &&
+        typeof value.componentId === 'string' &&
+        typeof value.path === 'string') {
+        return { store: true, issues: [] };
+    }
+    return {
+        store: false,
+        issues: [
+            issue('error', A2UI_ISSUE_CODES.TYPE_MISMATCH, `"${key}" on ${componentName} must be an array of ids or a template { componentId, path }`, { surfaceId, path })
+        ]
+    };
+}
+function validateAction(componentName, key, value, path, surfaceId) {
+    const issues = [];
+    if (!isPlainObject(value)) {
+        issues.push(issue('error', A2UI_ISSUE_CODES.TYPE_MISMATCH, `"${key}" on ${componentName} must be an action object`, {
+            surfaceId,
+            path
+        }));
+        return { store: false, issues };
+    }
+    if (isPlainObject(value.event)) {
+        const event = value.event;
+        if (typeof event.name !== 'string') {
+            issues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, `action.event.name is required on ${componentName}`, {
+                surfaceId,
+                path: `${path}/event/name`
+            }));
+            return { store: false, issues };
+        }
+        if ('context' in event) {
+            if (!isPlainObject(event.context)) {
+                issues.push(issue('error', A2UI_ISSUE_CODES.TYPE_MISMATCH, `action.event.context on ${componentName} must be an object`, {
+                    surfaceId,
+                    path: `${path}/event/context`
+                }));
+                return { store: false, issues };
+            }
+            for (const contextKey of Object.keys(event.context)) {
+                if (PROTO_KEYS.has(contextKey)) {
+                    issues.push(issue('error', A2UI_ISSUE_CODES.PROTOTYPE_POLLUTION, `Prohibited action context key "${contextKey}" on ${componentName}`, { surfaceId, path: `${path}/event/context/${contextKey}` }));
+                }
+            }
+        }
+        // Store even with a context-key error: the renderer builds context on a
+        // null-prototype object, so the flagged key is inert. The error still relays.
+        return { store: issues.every((i) => i.code !== A2UI_ISSUE_CODES.PROTOTYPE_POLLUTION), issues };
+    }
+    if (isPlainObject(value.functionCall)) {
+        if (typeof value.functionCall.call === 'string')
+            return { store: true, issues };
+        issues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, `action.functionCall.call is required on ${componentName}`, {
+            surfaceId,
+            path: `${path}/functionCall/call`
+        }));
+        return { store: false, issues };
+    }
+    issues.push(issue('error', A2UI_ISSUE_CODES.TYPE_MISMATCH, `"${key}" on ${componentName} must have an "event" or "functionCall"`, {
+        surfaceId,
+        path
+    }));
+    return { store: false, issues };
+}
+function validateOptions(componentName, key, value, path, surfaceId) {
+    const bad = (detail) => ({
+        store: false,
+        issues: [issue('error', A2UI_ISSUE_CODES.TYPE_MISMATCH, detail, { surfaceId, path })]
+    });
+    if (!Array.isArray(value))
+        return bad(`"${key}" on ${componentName} must be an array of { label, value } options`);
+    const issues = [];
+    const seenValues = new Set();
+    for (let i = 0; i < value.length; i++) {
+        const option = value[i];
+        if (!isPlainObject(option) ||
+            typeof option.value !== 'string' ||
+            !isDynamicString(option.label)) {
+            return bad(`option ${i} on ${componentName} must be { label, value:string }`);
+        }
+        // Duplicate option values must be flagged AND deduped downstream: a keyed
+        // `{#each}` on option.value would otherwise throw `each_key_duplicate` (a
+        // hard render crash that breaks the "never throw" contract).
+        if (seenValues.has(option.value)) {
+            issues.push(issue('warning', A2UI_ISSUE_CODES.DUPLICATE_OPTION, `Duplicate option value "${option.value}" on ${componentName} (the later option is dropped)`, { surfaceId, path: `${path}/${i}/value` }));
+        }
+        seenValues.add(option.value);
+        for (const labelIssue of dynamicRefIssues(option.label, `${path}/${i}/label`, surfaceId)) {
+            issues.push(labelIssue);
+        }
+    }
+    return { store: true, issues };
+}
+function validateIcon(value, path, surfaceId) {
+    if (typeof value === 'string') {
+        if (A2UI_ICON_NAMES.includes(value))
+            return { store: true, issues: [] };
+        return {
+            store: true,
+            issues: [
+                issue('warning', A2UI_ISSUE_CODES.ICON_UNMAPPED, `Icon "${value}" is not mapped; a fallback glyph is drawn`, {
+                    surfaceId,
+                    path
+                })
+            ]
+        };
+    }
+    if (isPlainObject(value)) {
+        if (typeof value.svgPath === 'string') {
+            if (A2UI_SVG_PATH_RE.test(value.svgPath))
+                return { store: true, issues: [] };
+            return {
+                store: true,
+                issues: [
+                    issue('warning', A2UI_ISSUE_CODES.ICON_INVALID_SVG, 'Icon svgPath failed the path grammar guard; a fallback glyph is drawn', {
+                        surfaceId,
+                        path
+                    })
+                ]
+            };
+        }
+        if (typeof value.path === 'string')
+            return { store: true, issues: dynamicRefIssues(value, path, surfaceId) }; // dynamic binding
+    }
+    return {
+        store: false,
+        issues: [
+            issue('error', A2UI_ISSUE_CODES.TYPE_MISMATCH, 'Icon name must be a mapped name, { svgPath } or { path }', { surfaceId, path })
+        ]
+    };
+}
+// ── Component validation ─────────────────────────────────────────────────────
+function validateComponent(surface, raw, envelopeIndex, compIndex, idsSeen) {
+    const base = `/messages/${envelopeIndex}/updateComponents/components/${compIndex}`;
+    const surfaceId = surface.surfaceId;
+    if (!isPlainObject(raw)) {
+        surface.issues.push(issue('error', A2UI_ISSUE_CODES.TYPE_MISMATCH, 'Component entry must be an object', {
+            surfaceId,
+            path: base
+        }));
+        return;
+    }
+    const comp = raw;
+    const id = comp.id;
+    if (typeof id !== 'string' || id === '') {
+        surface.issues.push(issue('error', A2UI_ISSUE_CODES.MISSING_ID, 'Component is missing a string "id"', {
+            surfaceId,
+            path: `${base}/id`
+        }));
+        return;
+    }
+    if (PROTO_KEYS.has(id)) {
+        surface.issues.push(issue('error', A2UI_ISSUE_CODES.PROTOTYPE_POLLUTION, `Prohibited component id "${id}"`, {
+            surfaceId,
+            path: `${base}/id`
+        }));
+        return;
+    }
+    if (idsSeen.has(id)) {
+        surface.issues.push(issue('error', A2UI_ISSUE_CODES.DUPLICATE_ID, `Duplicate component id "${id}" in one updateComponents (last wins)`, {
+            surfaceId,
+            path: `${base}/id`
+        }));
+    }
+    idsSeen.add(id);
+    const componentName = comp.component;
+    if (typeof componentName !== 'string') {
+        surface.issues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, `Component "${id}" is missing a string "component"`, { surfaceId, path: `${base}/component` }));
+        surface.components.set(id, { id, component: '', props: new Map(), sourceIndex: envelopeIndex });
+        return;
+    }
+    const spec = A2UI_REGISTRY[componentName];
+    if (!spec) {
+        if (UNSUPPORTED_A2UI_COMPONENTS.has(componentName)) {
+            surface.issues.push(issue('error', A2UI_ISSUE_CODES.UNSUPPORTED_COMPONENT, `Component "${componentName}" is not part of the rendered subset`, {
+                surfaceId,
+                path: `${base}/component`
+            }));
+        }
+        else {
+            surface.issues.push(issue('error', A2UI_ISSUE_CODES.UNKNOWN_COMPONENT, `Unknown component "${componentName}"`, {
+                surfaceId,
+                path: `${base}/component`
+            }));
+        }
+        surface.components.set(id, {
+            id,
+            component: componentName,
+            props: new Map(),
+            sourceIndex: envelopeIndex
+        });
+        return;
+    }
+    const props = new Map();
+    for (const key of Object.keys(comp)) {
+        if (key === 'id' || key === 'component')
+            continue;
+        if (PROTO_KEYS.has(key)) {
+            surface.issues.push(issue('error', A2UI_ISSUE_CODES.PROTOTYPE_POLLUTION, `Prohibited property "${key}" on "${id}"`, { surfaceId, path: `${base}/${key}` }));
+            continue;
+        }
+        if (A2UI_IGNORED_PROPS.has(key)) {
+            surface.issues.push(issue('warning', A2UI_ISSUE_CODES.IGNORED_PROP, `Property "${key}" on ${componentName} is not supported and is ignored`, {
+                surfaceId,
+                path: `${base}/${key}`
+            }));
+            continue;
+        }
+        const propSpec = spec.props[key];
+        if (!propSpec) {
+            surface.issues.push(issue('error', A2UI_ISSUE_CODES.UNKNOWN_PROP, `Unknown property "${key}" on ${componentName}`, { surfaceId, path: `${base}/${key}` }));
+            continue;
+        }
+        const result = validateProp(componentName, key, propSpec, comp[key], `${base}/${key}`, surfaceId);
+        for (const propIssue of result.issues)
+            surface.issues.push(propIssue);
+        if (result.store)
+            props.set(key, comp[key]);
+    }
+    for (const [key, propSpec] of Object.entries(spec.props)) {
+        if (propSpec.required && !props.has(key)) {
+            surface.issues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, `Required property "${key}" is missing on ${componentName} "${id}"`, {
+                surfaceId,
+                path: `${base}/${key}`
+            }));
+        }
+    }
+    if (componentName === 'ChoicePicker') {
+        if (props.get('displayStyle') === 'chips' || props.get('filterable') === true) {
+            surface.issues.push(issue('warning', A2UI_ISSUE_CODES.CHOICEPICKER_FALLBACK, `ChoicePicker "${id}" chips/filterable are rendered with a fallback`, {
+                surfaceId,
+                path: base
+            }));
+        }
+    }
+    if (componentName === 'DateTimeInput') {
+        // Both flags default to false in the spec — a DateTimeInput without either
+        // would have no input UI at all. We read tolerantly (render a date input)
+        // and report loudly so the agent fixes the payload.
+        if (props.get('enableDate') !== true && props.get('enableTime') !== true) {
+            surface.issues.push(issue('warning', A2UI_ISSUE_CODES.DATETIME_NO_MODE, `DateTimeInput "${id}" sets neither enableDate nor enableTime; rendering a date input`, {
+                surfaceId,
+                path: base
+            }));
+        }
+    }
+    surface.components.set(id, { id, component: componentName, props, sourceIndex: envelopeIndex });
+}
+// ── Envelope handlers ────────────────────────────────────────────────────────
+function flagExtraKeys(object, allowed, sink, surfaceId, base, container) {
+    for (const key of Object.keys(object)) {
+        if (allowed.has(key))
+            continue;
+        const code = PROTO_KEYS.has(key)
+            ? A2UI_ISSUE_CODES.PROTOTYPE_POLLUTION
+            : A2UI_ISSUE_CODES.UNKNOWN_PROP;
+        sink.push(issue('error', code, `Unexpected key "${key}" in ${container}`, {
+            surfaceId,
+            path: `${base}/${key}`
+        }));
+    }
+}
+const CREATE_SURFACE_KEYS = new Set([
+    'surfaceId',
+    'catalogId',
+    'theme',
+    'sendDataModel'
+]);
+const UPDATE_COMPONENTS_KEYS = new Set(['surfaceId', 'components']);
+const UPDATE_DATA_MODEL_KEYS = new Set(['surfaceId', 'path', 'value']);
+const DELETE_SURFACE_KEYS = new Set(['surfaceId']);
+function createProcessor() {
+    const surfaces = new Map();
+    const globalIssues = [];
+    function handleCreateSurface(env, base) {
+        const cs = env.createSurface;
+        if (!isPlainObject(cs)) {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, 'createSurface must be an object', {
+                path: `${base}/createSurface`
+            }));
+            return;
+        }
+        const surfaceId = cs.surfaceId;
+        if (typeof surfaceId !== 'string' || surfaceId === '') {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, 'createSurface.surfaceId is required', {
+                path: `${base}/createSurface/surfaceId`
+            }));
+            return;
+        }
+        const existing = surfaces.get(surfaceId);
+        if (existing) {
+            existing.issues.push(issue('error', A2UI_ISSUE_CODES.DUPLICATE_SURFACE, `Surface "${surfaceId}" already exists; delete it before recreating`, {
+                surfaceId,
+                path: `${base}/createSurface/surfaceId`
+            }));
+            return;
+        }
+        if (surfaces.size >= MAX_SURFACES) {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.MAX_SURFACES, `Surface count exceeds the limit of ${MAX_SURFACES}; "${surfaceId}" was not created`, { surfaceId, path: `${base}/createSurface/surfaceId` }));
+            return;
+        }
+        const surface = {
+            surfaceId,
+            components: new Map(),
+            dataModel: undefined,
+            issues: []
+        };
+        surfaces.set(surfaceId, surface);
+        if (typeof cs.catalogId !== 'string') {
+            surface.issues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, 'createSurface.catalogId is required', {
+                surfaceId,
+                path: `${base}/createSurface/catalogId`
+            }));
+        }
+        if ('theme' in cs) {
+            surface.issues.push(issue('warning', A2UI_ISSUE_CODES.SURFACE_PROP_IGNORED, 'theme is ignored', {
+                surfaceId,
+                path: `${base}/createSurface/theme`
+            }));
+        }
+        if ('sendDataModel' in cs) {
+            surface.issues.push(issue('warning', A2UI_ISSUE_CODES.SURFACE_PROP_IGNORED, 'sendDataModel is ignored', {
+                surfaceId,
+                path: `${base}/createSurface/sendDataModel`
+            }));
+        }
+        flagExtraKeys(cs, CREATE_SURFACE_KEYS, surface.issues, surfaceId, `${base}/createSurface`, 'createSurface');
+    }
+    function handleUpdateComponents(env, base, index) {
+        const uc = env.updateComponents;
+        if (!isPlainObject(uc)) {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, 'updateComponents must be an object', {
+                path: `${base}/updateComponents`
+            }));
+            return;
+        }
+        const surfaceId = uc.surfaceId;
+        if (typeof surfaceId !== 'string') {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, 'updateComponents.surfaceId is required', {
+                path: `${base}/updateComponents/surfaceId`
+            }));
+            return;
+        }
+        const surface = surfaces.get(surfaceId);
+        if (!surface) {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.NO_SURFACE, `updateComponents for unknown surface "${surfaceId}" (createSurface must come first)`, {
+                surfaceId,
+                path: `${base}/updateComponents`
+            }));
+            return;
+        }
+        flagExtraKeys(uc, UPDATE_COMPONENTS_KEYS, surface.issues, surfaceId, `${base}/updateComponents`, 'updateComponents');
+        const components = uc.components;
+        if (!Array.isArray(components) || components.length === 0) {
+            surface.issues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, 'updateComponents.components must be a non-empty array', {
+                surfaceId,
+                path: `${base}/updateComponents/components`
+            }));
+            return;
+        }
+        let limit = components.length;
+        if (limit > MAX_COMPONENTS_PER_UPDATE) {
+            surface.issues.push(issue('error', A2UI_ISSUE_CODES.MAX_COMPONENTS, `updateComponents carries ${components.length} components; only the first ${MAX_COMPONENTS_PER_UPDATE} are processed`, { surfaceId, path: `${base}/updateComponents/components` }));
+            limit = MAX_COMPONENTS_PER_UPDATE;
+        }
+        const idsSeen = new Set();
+        for (let i = 0; i < limit; i++) {
+            validateComponent(surface, components[i], index, i, idsSeen);
+        }
+    }
+    function handleUpdateDataModel(env, base) {
+        const udm = env.updateDataModel;
+        if (!isPlainObject(udm)) {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, 'updateDataModel must be an object', {
+                path: `${base}/updateDataModel`
+            }));
+            return;
+        }
+        const surfaceId = udm.surfaceId;
+        if (typeof surfaceId !== 'string') {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, 'updateDataModel.surfaceId is required', {
+                path: `${base}/updateDataModel/surfaceId`
+            }));
+            return;
+        }
+        const surface = surfaces.get(surfaceId);
+        if (!surface) {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.NO_SURFACE, `updateDataModel for unknown surface "${surfaceId}" (createSurface must come first)`, {
+                surfaceId,
+                path: `${base}/updateDataModel`
+            }));
+            return;
+        }
+        flagExtraKeys(udm, UPDATE_DATA_MODEL_KEYS, surface.issues, surfaceId, `${base}/updateDataModel`, 'updateDataModel');
+        const pathValue = udm.path;
+        if (pathValue !== undefined && typeof pathValue !== 'string') {
+            surface.issues.push(issue('error', A2UI_ISSUE_CODES.TYPE_MISMATCH, 'updateDataModel.path must be a string', {
+                surfaceId,
+                path: `${base}/updateDataModel/path`
+            }));
+            return;
+        }
+        const hasValue = 'value' in udm;
+        const whole = pathValue === undefined || pathValue === '' || pathValue === '/';
+        if (whole) {
+            surface.dataModel = hasValue ? cloneData(udm.value) : undefined;
+            return;
+        }
+        const pointer = pathValue;
+        if (!isContainer(surface.dataModel)) {
+            const firstSegment = pointer.replace(/^\//, '').split('/')[0];
+            surface.dataModel = /^(?:0|[1-9]\d*|-)$/.test(firstSegment) ? [] : {};
+        }
+        if (hasValue) {
+            const { issue: setIssue } = setAtPointer(surface.dataModel, pointer, cloneData(udm.value));
+            if (setIssue)
+                surface.issues.push({ ...setIssue, surfaceId });
+        }
+        else {
+            deleteAtPointer(surface.dataModel, pointer);
+        }
+    }
+    function handleDeleteSurface(env, base) {
+        const ds = env.deleteSurface;
+        if (!isPlainObject(ds)) {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, 'deleteSurface must be an object', {
+                path: `${base}/deleteSurface`
+            }));
+            return;
+        }
+        const surfaceId = ds.surfaceId;
+        if (typeof surfaceId !== 'string') {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.MISSING_FIELD, 'deleteSurface.surfaceId is required', {
+                path: `${base}/deleteSurface/surfaceId`
+            }));
+            return;
+        }
+        if (!surfaces.has(surfaceId)) {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.NO_SURFACE, `deleteSurface for unknown surface "${surfaceId}"`, { surfaceId, path: `${base}/deleteSurface` }));
+            return;
+        }
+        flagExtraKeys(ds, DELETE_SURFACE_KEYS, globalIssues, surfaceId, `${base}/deleteSurface`, 'deleteSurface');
+        surfaces.delete(surfaceId);
+    }
+    function apply(envelope, index) {
+        const base = `/messages/${index}`;
+        if (!isPlainObject(envelope)) {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.INVALID_ENVELOPE, 'Envelope must be a JSON object', {
+                path: base
+            }));
+            return;
+        }
+        const env = envelope;
+        if (typeof env.version !== 'string' || !A2UI_SUPPORTED_VERSIONS.includes(env.version)) {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.INVALID_VERSION, `Unsupported envelope version (expected one of: ${A2UI_SUPPORTED_VERSIONS.join(', ')})`, {
+                path: `${base}/version`
+            }));
+            return;
+        }
+        const present = OP_KEYS.filter((key) => key in env);
+        if (present.length !== 1) {
+            globalIssues.push(issue('error', A2UI_ISSUE_CODES.UNKNOWN_ENVELOPE_TYPE, `Envelope must contain exactly one of: ${OP_KEYS.join(', ')} (found ${present.length})`, { path: base }));
+            return;
+        }
+        const allowedTop = new Set(['version', present[0]]);
+        flagExtraKeys(env, allowedTop, globalIssues, undefined, base, 'envelope');
+        switch (present[0]) {
+            case 'createSurface':
+                handleCreateSurface(env, base);
+                break;
+            case 'updateComponents':
+                handleUpdateComponents(env, base, index);
+                break;
+            case 'updateDataModel':
+                handleUpdateDataModel(env, base);
+                break;
+            case 'deleteSurface':
+                handleDeleteSurface(env, base);
+                break;
+        }
+    }
+    return { surfaces, globalIssues, apply };
+}
+export function createA2uiProcessor() {
+    return createProcessor();
+}
+/**
+ * Normalize a render payload into an envelope list. Accepts an envelope array,
+ * a single envelope, or the golden-file `{ messages: [...] }` wrapper. Returns
+ * an `issue` (and no envelopes) only for wholly unusable input.
+ */
+export function normalizeA2uiPayload(payload) {
+    if (Array.isArray(payload))
+        return { envelopes: payload };
+    if (isPlainObject(payload)) {
+        if (Array.isArray(payload.messages))
+            return { envelopes: payload.messages };
+        return { envelopes: [payload] };
+    }
+    return {
+        envelopes: [],
+        issue: issue('error', A2UI_ISSUE_CODES.INVALID_ENVELOPE, 'A2UI payload must be an envelope, an array of envelopes, or { messages: [...] }')
+    };
+}
+/**
+ * Walk the component graph from `root` and collect structural faults that only
+ * exist once components are assembled: cycles, excessive depth/nodes, dangling
+ * child references, non-array template paths, and mis-placed `weight`.
+ *
+ * NOTE — contract extension. The design's published `a2ui-validate.ts` surface
+ * is `createA2uiProcessor` + `normalizeA2uiPayload`. This function is an
+ * additive export (no existing signature changed): the renderer (WP-B) needs
+ * render-time graph faults whose severity depends on the `streaming` flag, and
+ * the test suite exercises them here. Traversal is bounded by `maxNodes` so a
+ * template over a huge array cannot DoS the walk itself.
+ */
+export function collectGraphIssues(surface, options) {
+    const streaming = options?.streaming ?? false;
+    const maxDepth = options?.maxDepth ?? 32;
+    const maxNodes = options?.maxNodes ?? 512;
+    const surfaceId = surface.surfaceId;
+    const components = surface.components;
+    const issues = [];
+    if (!components.has('root')) {
+        if (!streaming) {
+            issues.push(issue('error', A2UI_ISSUE_CODES.MISSING_ROOT, 'No component with id "root" was defined', {
+                surfaceId
+            }));
+        }
+        return issues;
+    }
+    const reportedDangling = new Set();
+    let nodeCount = 0;
+    let overflowReported = false;
+    let aborted = false;
+    const childTargets = (comp, scopePrefix) => {
+        const out = [];
+        const single = comp.props.get('child');
+        if (typeof single === 'string')
+            out.push({ id: single, scope: scopePrefix });
+        const children = comp.props.get('children');
+        if (Array.isArray(children)) {
+            for (const childId of children)
+                if (typeof childId === 'string')
+                    out.push({ id: childId, scope: scopePrefix });
+        }
+        else if (children && typeof children === 'object') {
+            const template = children;
+            if (typeof template.componentId === 'string' && typeof template.path === 'string') {
+                const absPath = template.path.startsWith('/')
+                    ? template.path
+                    : `${scopePrefix ?? ''}/${template.path}`;
+                const list = getAtPointer(surface.dataModel, absPath);
+                if (Array.isArray(list)) {
+                    for (let i = 0; i < list.length; i++) {
+                        out.push({ id: template.componentId, scope: `${absPath}/${i}` });
+                        if (out.length > maxNodes)
+                            break; // bound expansion
+                    }
+                }
+                else if (list !== undefined) {
+                    issues.push(issue('warning', A2UI_ISSUE_CODES.TEMPLATE_PATH_NOT_ARRAY, `Template path "${absPath}" did not resolve to an array`, {
+                        surfaceId
+                    }));
+                }
+                // list === undefined → data not present yet; render nothing (graceful).
+            }
+        }
+        return out;
+    };
+    const visit = (id, depth, stack, parentComponent, scopePrefix) => {
+        if (aborted)
+            return;
+        nodeCount++;
+        if (nodeCount > maxNodes) {
+            if (!overflowReported) {
+                issues.push(issue('error', A2UI_ISSUE_CODES.MAX_NODES, `Rendered node count exceeds the limit of ${maxNodes}`, { surfaceId }));
+                overflowReported = true;
+            }
+            aborted = true;
+            return;
+        }
+        if (depth > maxDepth) {
+            issues.push(issue('error', A2UI_ISSUE_CODES.MAX_DEPTH, `Component tree depth exceeds the limit of ${maxDepth}`, { surfaceId }));
+            return;
+        }
+        const comp = components.get(id);
+        if (!comp) {
+            if (!reportedDangling.has(id)) {
+                reportedDangling.add(id);
+                issues.push(issue(streaming ? 'warning' : 'error', A2UI_ISSUE_CODES.DANGLING_REF, `Reference to undefined component "${id}"`, { surfaceId }));
+            }
+            return;
+        }
+        if (comp.props.has('weight') && parentComponent !== 'Row' && parentComponent !== 'Column') {
+            issues.push(issue('warning', A2UI_ISSUE_CODES.WEIGHT_CONTEXT, `"weight" on "${id}" is only honored as a direct child of Row or Column`, {
+                surfaceId
+            }));
+        }
+        const nextStack = new Set(stack);
+        nextStack.add(id);
+        for (const target of childTargets(comp, scopePrefix)) {
+            if (aborted)
+                return;
+            if (nextStack.has(target.id)) {
+                issues.push(issue('error', A2UI_ISSUE_CODES.CYCLE, `Cycle detected at component "${target.id}"`, {
+                    surfaceId
+                }));
+                continue;
+            }
+            visit(target.id, depth + 1, nextStack, comp.component, target.scope);
+        }
+    };
+    visit('root', 0, new Set(), null, undefined);
+    return issues;
+}