@llm4ts/shell 2.12.0 → 2.13.0

package/kits/soap-ace/flows/lib/soap/Instance.js

@@ -0,0 +1,675 @@
+import { ComplexTypeDef, isBuiltin, localName, SimpleTypeDef, splitClark, typeByName } from "./Catalog.js";
+import { kindForName } from "./Masking.js";
+import { escapeAttribute, escapeText, elements, textOf } from "./Xml.js";
+import { isYamlList, isYamlMap, yamlKey, yamlScalar } from "./Yaml.js";
+// Instances of catalog types as plain value trees (the shape request files
+// are written in): the commented YAML skeleton of a request, validation of
+// a value against its XSD type, and conversion both ways between values and
+// XML. Leaves are strings (XML text); `null` is `xsi:nil`. Attributes are
+// keys starting with `@`; the text of a simple-content type is `#text`.
+// Child order on the wire follows the XSD sequence, not the file.
+export const XsiNamespace = "http://www.w3.org/2001/XMLSchema-instance";
+export const simpleView = (catalog, name) => {
+    const facets = [];
+    const chain = [];
+    let current = name;
+    for (let depth = 0; depth < 16 && !isBuiltin(current); depth++) {
+        const type = typeByName(catalog, current);
+        if (!(type instanceof SimpleTypeDef))
+            break;
+        facets.push(type.facets);
+        chain.push(localName(type.name));
+        current = type.base;
+    }
+    return { builtin: isBuiltin(current) ? localName(current) : "string", facets, chain };
+};
+const integerTypes = new Set([
+    "int",
+    "integer",
+    "long",
+    "short",
+    "byte",
+    "nonNegativeInteger",
+    "positiveInteger",
+    "nonPositiveInteger",
+    "negativeInteger",
+    "unsignedInt",
+    "unsignedLong",
+    "unsignedShort",
+    "unsignedByte"
+]);
+const lexical = {
+    boolean: /^(true|false|1|0)$/,
+    decimal: /^[+-]?(\d+(\.\d*)?|\.\d+)$/,
+    float: /^([+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?|INF|-INF|NaN)$/,
+    double: /^([+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?|INF|-INF|NaN)$/,
+    date: /^-?\d{4,}-\d{2}-\d{2}(Z|[+-]\d{2}:\d{2})?$/,
+    dateTime: /^-?\d{4,}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/,
+    time: /^\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/,
+    gYear: /^-?\d{4,}(Z|[+-]\d{2}:\d{2})?$/,
+    base64Binary: /^[A-Za-z0-9+/\s]*=?=?\s*$/,
+    hexBinary: /^([0-9A-Fa-f]{2})*$/
+};
+/** XSD patterns are implicitly anchored and mostly JS-compatible. */
+const xsdRegex = (pattern) => {
+    try {
+        return new RegExp(`^(?:${pattern.replace(/\\i/g, "[A-Za-z_:]").replace(/\\c/g, "[A-Za-z0-9._:-]")})$`, "u");
+    }
+    catch {
+        return undefined;
+    }
+};
+const digitsOf = (value) => {
+    const unsigned = value.replace(/^[+-]/, "");
+    const [whole = "", fraction = ""] = unsigned.split(".");
+    const trimmedFraction = fraction.replace(/0+$/, "");
+    return {
+        total: whole.replace(/^0+(?=\d)/, "").length + trimmedFraction.length,
+        fraction: trimmedFraction.length
+    };
+};
+export const checkSimple = (catalog, type, value) => {
+    const view = simpleView(catalog, type);
+    const problems = [];
+    const builtin = view.builtin;
+    if (integerTypes.has(builtin)) {
+        if (!/^[+-]?\d+$/.test(value))
+            problems.push(`"${value}" is not an ${builtin}`);
+    }
+    else {
+        const shape = lexical[builtin];
+        if (shape !== undefined && !shape.test(value))
+            problems.push(`"${value}" is not a ${builtin}`);
+    }
+    const numeric = integerTypes.has(builtin) || ["decimal", "float", "double"].includes(builtin);
+    for (const facets of view.facets) {
+        if (facets.enumeration !== undefined && !facets.enumeration.includes(value)) {
+            problems.push(`"${value}" is not one of ${facets.enumeration.join(", ")}`);
+        }
+        if (facets.pattern !== undefined && facets.pattern.length > 0) {
+            const matches = facets.pattern.some((pattern) => xsdRegex(pattern)?.test(value) ?? true);
+            if (!matches)
+                problems.push(`"${value}" does not match ${facets.pattern.join(" | ")}`);
+        }
+        const length = [...value].length;
+        if (facets.length !== undefined && length !== facets.length) {
+            problems.push(`length ${length}, expected ${facets.length}`);
+        }
+        if (facets.minLength !== undefined && length < facets.minLength) {
+            problems.push(`length ${length} below ${facets.minLength}`);
+        }
+        if (facets.maxLength !== undefined && length > facets.maxLength) {
+            problems.push(`length ${length} above ${facets.maxLength}`);
+        }
+        if (numeric && /^[+-]?(\d+(\.\d*)?|\.\d+)$/.test(value)) {
+            const number = Number(value);
+            const digits = digitsOf(value);
+            if (facets.totalDigits !== undefined && digits.total > facets.totalDigits) {
+                problems.push(`${digits.total} digits, at most ${facets.totalDigits}`);
+            }
+            if (facets.fractionDigits !== undefined && digits.fraction > facets.fractionDigits) {
+                problems.push(`${digits.fraction} fraction digits, at most ${facets.fractionDigits}`);
+            }
+            if (facets.minInclusive !== undefined && number < Number(facets.minInclusive)) {
+                problems.push(`${value} below ${facets.minInclusive}`);
+            }
+            if (facets.maxInclusive !== undefined && number > Number(facets.maxInclusive)) {
+                problems.push(`${value} above ${facets.maxInclusive}`);
+            }
+            if (facets.minExclusive !== undefined && number <= Number(facets.minExclusive)) {
+                problems.push(`${value} not above ${facets.minExclusive}`);
+            }
+            if (facets.maxExclusive !== undefined && number >= Number(facets.maxExclusive)) {
+                problems.push(`${value} not below ${facets.maxExclusive}`);
+            }
+        }
+    }
+    return problems;
+};
+// ---------------------------------------------------------------------------
+// Example values
+/** A string matching a simple XSD pattern: literals, classes, groups (first branch), quantifiers. */
+export const patternExample = (pattern) => {
+    let index = 0;
+    const atom = () => {
+        const char = pattern[index];
+        if (char === undefined)
+            return undefined;
+        if (char === "(") {
+            index++;
+            const start = index;
+            let depth = 1;
+            while (index < pattern.length && depth > 0) {
+                if (pattern[index] === "\\")
+                    index++;
+                else if (pattern[index] === "(")
+                    depth++;
+                else if (pattern[index] === ")")
+                    depth--;
+                index++;
+            }
+            const inner = pattern.slice(start, index - 1).replace(/^\?:/, "");
+            let branchDepth = 0;
+            let cut = inner.length;
+            for (let position = 0; position < inner.length; position++) {
+                const current = inner[position];
+                if (current === "\\")
+                    position++;
+                else if (current === "(" || current === "[")
+                    branchDepth++;
+                else if (current === ")" || current === "]")
+                    branchDepth--;
+                else if (current === "|" && branchDepth === 0) {
+                    cut = position;
+                    break;
+                }
+            }
+            return patternExample(inner.slice(0, cut));
+        }
+        if (char === "[") {
+            const end = pattern.indexOf("]", index + 1);
+            if (end < 0)
+                return undefined;
+            const body = pattern.slice(index + 1, end);
+            index = end + 1;
+            if (body.startsWith("^"))
+                return undefined;
+            if (body.startsWith("\\d") || /^0-9/.test(body))
+                return "0";
+            const first = body.startsWith("\\") ? body[1] : body[0];
+            return first === undefined ? undefined : first;
+        }
+        if (char === "\\") {
+            const escaped = pattern[index + 1];
+            index += 2;
+            if (escaped === "d")
+                return "0";
+            if (escaped === "w")
+                return "a";
+            if (escaped === "s")
+                return " ";
+            if (escaped === undefined)
+                return undefined;
+            return /[A-Za-z]/.test(escaped) ? undefined : escaped;
+        }
+        if (char === ".") {
+            index++;
+            return "a";
+        }
+        if ("|)*+?{".includes(char))
+            return undefined;
+        index++;
+        return char;
+    };
+    let result = "";
+    while (index < pattern.length) {
+        if (pattern[index] === "|")
+            break;
+        const piece = atom();
+        if (piece === undefined)
+            return undefined;
+        const quantifier = /^(\{(\d+)(,(\d*))?\}|\*|\+|\?)/.exec(pattern.slice(index));
+        let count = 1;
+        if (quantifier !== null) {
+            index += quantifier[0].length;
+            if (quantifier[0] === "*" || quantifier[0] === "?")
+                count = 0;
+            else if (quantifier[2] !== undefined)
+                count = Number(quantifier[2]);
+        }
+        result += piece.repeat(count);
+    }
+    return result;
+};
+// Public example identifiers, valid by checksum; no real person or account.
+const kindExamples = {
+    iban: "IT60X0542811101000000123456",
+    "codice-fiscale": "RSSMRA85T10A562S",
+    "partita-iva": "12345678903",
+    pan: "4111111111111111",
+    email: "mario.rossi@example.invalid",
+    phone: "+39 333 1234567",
+    "birth-date": "1985-12-10"
+};
+const builtinExamples = {
+    boolean: "false",
+    decimal: "100.00",
+    float: "1.0",
+    double: "1.0",
+    date: "2026-01-15",
+    dateTime: "2026-01-15T10:00:00Z",
+    time: "10:00:00",
+    gYear: "2026",
+    base64Binary: "",
+    hexBinary: ""
+};
+/** An example value for a field: a seed, then field meaning, then facets, then the builtin. */
+export const exampleValue = (catalog, field, seeds = new Map()) => {
+    const seeded = seeds.get(field.name);
+    if (seeded !== undefined)
+        return seeded;
+    const view = simpleView(catalog, field.type);
+    const candidates = [];
+    const kind = kindForName(field.name) ?? kindForName(localName(field.type).replace(/Type$/, ""));
+    if (kind !== undefined && kindExamples[kind] !== undefined)
+        candidates.push(kindExamples[kind] ?? "");
+    if (/divisa|currency|valuta$/i.test(field.name) ||
+        /divisa|currency/i.test(view.chain.join(" "))) {
+        candidates.push("EUR");
+    }
+    for (const facets of view.facets) {
+        if (facets.enumeration?.[0] !== undefined)
+            candidates.push(facets.enumeration[0]);
+        for (const pattern of facets.pattern ?? []) {
+            const example = patternExample(pattern);
+            if (example !== undefined)
+                candidates.push(example);
+        }
+        if (facets.minInclusive !== undefined)
+            candidates.push(facets.minInclusive);
+    }
+    if (integerTypes.has(view.builtin))
+        candidates.push("1");
+    const builtinExample = builtinExamples[view.builtin];
+    if (builtinExample !== undefined)
+        candidates.push(builtinExample);
+    const maxLength = Math.min(...view.facets.map((facets) => facets.maxLength ?? facets.length ?? 64));
+    candidates.push(field.name.slice(0, Math.max(1, maxLength)));
+    return (candidates.find((candidate) => checkSimple(catalog, field.type, candidate).length === 0) ??
+        candidates[0] ??
+        "");
+};
+// ---------------------------------------------------------------------------
+// Skeleton
+const describeSimple = (catalog, type) => {
+    const view = simpleView(catalog, type);
+    const named = view.chain.filter((name) => !name.startsWith("~"));
+    const parts = [...named.slice(0, 1), view.builtin];
+    for (const facets of view.facets) {
+        if (facets.enumeration !== undefined)
+            parts.push(`one of ${facets.enumeration.join(" | ")}`);
+        for (const pattern of facets.pattern ?? []) {
+            if (pattern.length <= 40)
+                parts.push(`pattern ${pattern}`);
+        }
+        if (facets.length !== undefined)
+            parts.push(`length ${facets.length}`);
+        if (facets.minLength !== undefined || facets.maxLength !== undefined) {
+            parts.push(`length ${facets.minLength ?? 0}..${facets.maxLength ?? "*"}`);
+        }
+        if (facets.totalDigits !== undefined)
+            parts.push(`${facets.totalDigits} digits`);
+        if (facets.fractionDigits !== undefined)
+            parts.push(`${facets.fractionDigits} decimals`);
+        if (facets.minInclusive !== undefined || facets.maxInclusive !== undefined) {
+            parts.push(`${facets.minInclusive ?? "…"}..${facets.maxInclusive ?? "…"}`);
+        }
+    }
+    return [...new Set(parts)].join(", ");
+};
+const occursText = (field) => field.maxOccurs === "unbounded"
+    ? `${field.minOccurs}..*`
+    : field.minOccurs === field.maxOccurs
+        ? `${field.minOccurs}`
+        : `${field.minOccurs}..${field.maxOccurs}`;
+/**
+ * The commented YAML body of an instance of `element`: required fields with
+ * example values and a type note, optional ones as commented lines, choice
+ * alternatives after the first commented as `or`.
+ */
+export const skeletonYaml = (catalog, element, indent, options = {}) => {
+    const maxDepth = options.maxDepth ?? 8;
+    const lines = [];
+    const emit = (depth, text) => lines.push(`${" ".repeat(depth)}${text}`);
+    const complexBody = (type, depth, level, commented) => {
+        const hash = commented ? "# " : "";
+        for (const attribute of type.attributes) {
+            const value = exampleValue(catalog, attribute, options.seeds);
+            const optional = !attribute.required && options.includeOptional !== true;
+            emit(depth, `${hash}${optional ? "# " : ""}${yamlKey(`@${attribute.name}`)}: ${yamlScalar(value)}  # attribute, ${describeSimple(catalog, attribute.type)}`);
+        }
+        if (type.textType !== undefined) {
+            emit(depth, `${hash}"#text": ${yamlScalar(exampleValue(catalog, { name: localName(type.name), type: type.textType }, options.seeds))}`);
+        }
+        // The first alternative of each choice is written out; the others (whole
+        // branches, not single fields) are commented as `or`.
+        const firstBranch = new Map();
+        for (const field of type.fields) {
+            if (field.choice !== undefined && !firstBranch.has(field.choice))
+                firstBranch.set(field.choice, field.branch);
+        }
+        for (const field of type.fields) {
+            const alternative = field.choice !== undefined && firstBranch.get(field.choice) !== field.branch;
+            const optional = field.minOccurs === 0 && options.includeOptional !== true;
+            const comment = commented || optional || alternative;
+            fieldLines(field, depth, level, comment, alternative);
+        }
+    };
+    const fieldLines = (field, depth, level, commented, alternative) => {
+        const hash = commented ? "# " : "";
+        const note = `${alternative ? "or, " : ""}${occursText(field)}${field.nillable ? ", nillable" : ""}`;
+        const repeated = field.maxOccurs === "unbounded" || field.maxOccurs > 1;
+        const type = typeByName(catalog, field.type);
+        const key = yamlKey(field.name);
+        if (type instanceof ComplexTypeDef) {
+            const doc = field.documentation ?? type.documentation;
+            emit(depth, `${hash}${key}:  # ${localName(field.type).replace(/^~/, "")} [${note}]${doc === undefined ? "" : ` — ${doc}`}`);
+            if (level >= maxDepth) {
+                emit(depth + 2, `# … nested deeper than ${maxDepth} levels`);
+                return;
+            }
+            const header = lines.length - 1;
+            if (repeated) {
+                emit(depth + 2, `${hash}-`);
+                complexBody(type, depth + 4, level + 1, commented);
+            }
+            else {
+                complexBody(type, depth + 2, level + 1, commented);
+            }
+            // A required element whose children are all optional is written as
+            // an explicit empty map, never as a key with only comments (null).
+            if (!commented &&
+                lines
+                    .slice(header + 1)
+                    .every((line) => line.trimStart().startsWith("#") || line.trim() === "-")) {
+                if (repeated) {
+                    const dash = lines.findIndex((line, index) => index > header && line.trim() === "-");
+                    if (dash >= 0)
+                        lines[dash] = `${" ".repeat(depth + 2)}- {}`;
+                }
+                else {
+                    lines[header] = (lines[header] ?? "").replace(/^(\s*[^:]+):/, "$1: {}");
+                }
+            }
+            return;
+        }
+        const value = exampleValue(catalog, field, options.seeds);
+        const description = describeSimple(catalog, field.type);
+        const doc = field.documentation === undefined ? "" : ` — ${field.documentation}`;
+        if (repeated) {
+            emit(depth, `${hash}${key}:  # ${description} [${note}]${doc}`);
+            emit(depth + 2, `${hash}- ${yamlScalar(value)}`);
+        }
+        else {
+            emit(depth, `${hash}${key}: ${yamlScalar(value)}  # ${description} [${note}]${doc}`);
+        }
+    };
+    const root = typeByName(catalog, element.type);
+    if (root instanceof ComplexTypeDef)
+        complexBody(root, indent, 1, false);
+    else
+        emit(indent, `"#text": ${yamlScalar(exampleValue(catalog, { name: localName(element.name), type: element.type }, options.seeds))}  # ${describeSimple(catalog, element.type)}`);
+    return lines;
+};
+// ---------------------------------------------------------------------------
+// Validation of values
+const join = (path, segment) => path === "" ? segment : `${path}.${segment}`;
+const validateComplex = (catalog, type, value, path, issues) => {
+    const known = new Set([
+        ...type.fields.map((field) => field.name),
+        ...type.attributes.map((attribute) => `@${attribute.name}`),
+        ...(type.textType === undefined ? [] : ["#text"])
+    ]);
+    for (const key of Object.keys(value)) {
+        if (!known.has(key))
+            issues.push({
+                path: join(path, key),
+                detail: `not a field of ${localName(type.name).replace(/^~/, "")}`
+            });
+    }
+    for (const attribute of type.attributes) {
+        const item = value[`@${attribute.name}`];
+        if (item === undefined || item === null) {
+            if (attribute.required)
+                issues.push({
+                    path: join(path, `@${attribute.name}`),
+                    detail: "required attribute is missing"
+                });
+        }
+        else if (typeof item !== "string") {
+            issues.push({
+                path: join(path, `@${attribute.name}`),
+                detail: "an attribute holds a single value"
+            });
+        }
+        else {
+            for (const problem of checkSimple(catalog, attribute.type, item)) {
+                issues.push({ path: join(path, `@${attribute.name}`), detail: problem });
+            }
+        }
+    }
+    if (type.textType !== undefined) {
+        const text = value["#text"];
+        if (typeof text === "string") {
+            for (const problem of checkSimple(catalog, type.textType, text))
+                issues.push({ path: join(path, "#text"), detail: problem });
+        }
+    }
+    // Choices: at most one alternative (branch) present; inside the chosen
+    // one its required fields are required; a required choice needs one.
+    const branches = new Map();
+    for (const field of type.fields) {
+        if (field.choice === undefined)
+            continue;
+        const byBranch = branches.get(field.choice) ?? new Map();
+        byBranch.set(field.branch, [...(byBranch.get(field.branch) ?? []), field.name]);
+        branches.set(field.choice, byBranch);
+    }
+    const taken = new Map();
+    for (const field of type.fields) {
+        if (field.choice !== undefined && value[field.name] !== undefined) {
+            taken.set(field.choice, new Set([...(taken.get(field.choice) ?? []), field.branch]));
+        }
+    }
+    const where = path === "" ? "(root)" : path;
+    const label = (choice, branch) => (branches.get(choice)?.get(branch) ?? []).join(" + ");
+    for (const [choice, present] of taken) {
+        if (present.size > 1) {
+            issues.push({
+                path: where,
+                detail: `choose one of ${[...present].map((branch) => label(choice, branch)).join(", ")}`
+            });
+        }
+    }
+    for (const [choice, byBranch] of branches) {
+        if ((taken.get(choice)?.size ?? 0) > 0)
+            continue;
+        const required = type.fields.some((field) => field.choice === choice && field.minOccurs > 0);
+        if (required) {
+            issues.push({
+                path: where,
+                detail: `one of ${[...byBranch.keys()].map((branch) => label(choice, branch)).join(", ")} is required`
+            });
+        }
+    }
+    for (const field of type.fields) {
+        const item = value[field.name];
+        const fieldPath = join(path, field.name);
+        if (item === undefined) {
+            const inTakenBranch = field.choice !== undefined && (taken.get(field.choice)?.has(field.branch) ?? false);
+            if (field.minOccurs > 0 && (field.choice === undefined || inTakenBranch)) {
+                issues.push({ path: fieldPath, detail: "required field is missing" });
+            }
+            continue;
+        }
+        const items = isYamlList(item) ? item : [item];
+        const repeated = field.maxOccurs === "unbounded" || field.maxOccurs > 1;
+        if (isYamlList(item) && !repeated) {
+            issues.push({ path: fieldPath, detail: "occurs at most once; write a single value" });
+        }
+        if (items.length < field.minOccurs)
+            issues.push({ path: fieldPath, detail: `at least ${field.minOccurs} occurrences` });
+        if (field.maxOccurs !== "unbounded" && items.length > field.maxOccurs) {
+            issues.push({ path: fieldPath, detail: `at most ${field.maxOccurs} occurrences` });
+        }
+        items.forEach((entry, position) => {
+            validateValue(catalog, field.type, field.nillable, entry, isYamlList(item) ? `${fieldPath}[${position}]` : fieldPath, issues);
+        });
+    }
+};
+const validateValue = (catalog, typeName, nillable, value, path, issues) => {
+    if (value === null) {
+        if (!nillable)
+            issues.push({ path, detail: "is not nillable; give a value or remove the field" });
+        return;
+    }
+    const type = typeByName(catalog, typeName);
+    if (type instanceof ComplexTypeDef) {
+        if (typeof value === "string" && type.textType !== undefined) {
+            validateComplex(catalog, type, { "#text": value }, path, issues);
+        }
+        else if (!isYamlMap(value)) {
+            issues.push({ path, detail: `expects fields of ${localName(type.name).replace(/^~/, "")}` });
+        }
+        else {
+            validateComplex(catalog, type, value, path, issues);
+        }
+        return;
+    }
+    if (typeof value !== "string") {
+        issues.push({ path, detail: "expects a single value" });
+        return;
+    }
+    for (const problem of checkSimple(catalog, typeName, value))
+        issues.push({ path, detail: problem });
+};
+/** Validate a value tree against a global element's type. */
+export const validateInstance = (catalog, element, value) => {
+    const issues = [];
+    validateValue(catalog, element.type, element.nillable, value, "", issues);
+    return issues.map((issue) => (issue.path === "" ? { ...issue, path: "(root)" } : issue));
+};
+// ---------------------------------------------------------------------------
+// Value → XML
+/** Serialize an instance of `element` with prefixes `ns1`, `ns2`… declared on the root. */
+export const instanceToXml = (catalog, element, value) => {
+    const prefixes = new Map();
+    const prefixOf = (namespace) => {
+        if (namespace === "")
+            return "";
+        let prefix = prefixes.get(namespace);
+        if (prefix === undefined) {
+            prefix = `ns${prefixes.size + 1}`;
+            prefixes.set(namespace, prefix);
+        }
+        return prefix;
+    };
+    let usesXsi = false;
+    const qualified = (namespace, local) => {
+        const prefix = prefixOf(namespace);
+        return prefix === "" ? local : `${prefix}:${local}`;
+    };
+    const write = (name, typeName, item) => {
+        if (item === null) {
+            usesXsi = true;
+            return `<${name} xsi:nil="true"/>`;
+        }
+        const type = typeByName(catalog, typeName);
+        if (!(type instanceof ComplexTypeDef)) {
+            return `<${name}>${escapeText(typeof item === "string" ? item : "")}</${name}>`;
+        }
+        const map = typeof item === "string" ? { "#text": item } : isYamlMap(item) ? item : {};
+        const attributes = type.attributes
+            .flatMap((attribute) => {
+            const attributeValue = map[`@${attribute.name}`];
+            return typeof attributeValue === "string"
+                ? [` ${attribute.name}="${escapeAttribute(attributeValue)}"`]
+                : [];
+        })
+            .join("");
+        const text = typeof map["#text"] === "string" ? escapeText(map["#text"]) : "";
+        const children = type.fields
+            .flatMap((field) => {
+            const child = map[field.name];
+            if (child === undefined)
+                return [];
+            const entries = isYamlList(child) ? child : [child];
+            return entries.map((entry) => write(qualified(field.namespace, field.name), field.type, entry));
+        })
+            .join("");
+        const content = `${text}${children}`;
+        return content === "" ? `<${name}${attributes}/>` : `<${name}${attributes}>${content}</${name}>`;
+    };
+    const root = splitClark(element.name);
+    const rootName = qualified(root.namespace, root.local);
+    const body = write(rootName, element.type, value);
+    const declarations = [
+        ...[...prefixes].map(([namespace, prefix]) => ` xmlns:${prefix}="${escapeAttribute(namespace)}"`),
+        ...(usesXsi ? [` xmlns:xsi="${XsiNamespace}"`] : [])
+    ].join("");
+    return body.replace(/^<([^\s/>]+)/, `<$1${declarations}`);
+};
+// ---------------------------------------------------------------------------
+// XML → value
+/**
+ * Read an XML element as an instance of `element`'s type. Unknown children,
+ * wrong namespaces, and repeated singletons become issues; values are kept
+ * as found so a response can be analysed even when it breaks its schema.
+ */
+export const instanceFromXml = (catalog, element, xml) => {
+    const issues = [];
+    const expected = splitClark(element.name);
+    if (xml.name.local !== expected.local || xml.name.namespace !== expected.namespace) {
+        issues.push({
+            path: "(root)",
+            detail: `expected {${expected.namespace}}${expected.local}, found {${xml.name.namespace}}${xml.name.local}`
+        });
+    }
+    const nil = (node) => node.attributes.some((attribute) => attribute.name.namespace === XsiNamespace &&
+        attribute.name.local === "nil" &&
+        (attribute.value === "true" || attribute.value === "1"));
+    const read = (node, typeName, path) => {
+        if (nil(node))
+            return null;
+        const type = typeByName(catalog, typeName);
+        if (!(type instanceof ComplexTypeDef))
+            return textOf(node);
+        const result = {};
+        for (const attribute of node.attributes) {
+            if (attribute.name.namespace === XsiNamespace)
+                continue;
+            if (!type.attributes.some((declared) => declared.name === attribute.name.local)) {
+                issues.push({
+                    path: join(path, `@${attribute.name.local}`),
+                    detail: "attribute not declared"
+                });
+            }
+            result[`@${attribute.name.local}`] = attribute.value;
+        }
+        if (type.textType !== undefined)
+            result["#text"] = textOf(node);
+        else if (textOf(node).trim() !== "")
+            issues.push({ path: path === "" ? "(root)" : path, detail: "unexpected text content" });
+        for (const child of elements(node)) {
+            const field = type.fields.find((candidate) => candidate.name === child.name.local);
+            const childPath = join(path, child.name.local);
+            if (field === undefined) {
+                // Kept as text; validation reports it as not a field of the type.
+                result[child.name.local] = textOf(child);
+                continue;
+            }
+            if (child.name.namespace !== field.namespace) {
+                issues.push({
+                    path: childPath,
+                    detail: `namespace ${child.name.namespace === "" ? "(none)" : child.name.namespace}, expected ${field.namespace === "" ? "(none)" : field.namespace}`
+                });
+            }
+            const childValue = read(child, field.type, childPath);
+            const repeated = field.maxOccurs === "unbounded" || field.maxOccurs > 1;
+            const existing = result[field.name];
+            if (repeated) {
+                const prior = existing !== undefined && isYamlList(existing) ? existing : [];
+                result[field.name] = [...prior, childValue];
+            }
+            else if (existing !== undefined) {
+                issues.push({ path: childPath, detail: "occurs more than once" });
+            }
+            else {
+                result[field.name] = childValue;
+            }
+        }
+        return result;
+    };
+    const value = read(xml, element.type, "");
+    return { value, issues: [...issues, ...validateInstance(catalog, element, value)] };
+};