@techspokes/typescript-wsdl-client 1.1.3 → 1.1.5

package/docs/content-model-gateway-feasibility.md

@@ -0,0 +1,169 @@
+# Content Model Gateway Feasibility
+
+Executed S02 #170 evidence for validation, representation and serialized-byte boundaries. See the root [README](../README.md).
+
+## Scope and disposition
+
+This bounded probe supports ADR 003's draft-07 runtime and serializer lowering, route-local non-mutating validation, and independently validated JSON serialization fallback. It introduces fixtures and tests only; the current gateway emitter and unrelated host policy remain unchanged.
+
+The [ADR](decisions/003-content-model-contracts.md#portable-contracts-and-dialects-s02-d05-s02-d06) defines the architecture; the [decision register](content-model-decisions.md) owns final dispositions. This document records executed observations, primary documentation, unverified combinations and first-consumer gates for #197/#198/#199/#200.
+
+## Reproduction and inspected versions
+
+The executable corpus is [the gateway feasibility integration test](../test/integration/content-model-gateway-feasibility.test.ts). Its [route helper](../test/helpers/contentModelGatewayProbe.ts) uses installed Ajv and serializer engines, not another schema or semantic engine.
+
+The reviewed draft checkpoint was `2f88ec81f77f4fc5a06b78f2d507ae8e20fe7a7c`. The following installed versions were observed after `npm ci --cache tmp/cache/npm` on Node `24.19.0`; the lockfile, rather than package ranges, determines this evidence.
+
+| Component | Installed version | Role |
+|---|---|---|
+| Fastify | 5.12.5 | HTTP routes and injection |
+| Ajv | 8.20.0 | Runtime JSON validation |
+| `@fastify/ajv-compiler` | 4.0.6 | Host default validator |
+| `fast-json-stringify` | 7.0.1 | Schema serializer |
+| `@fastify/fast-json-stringify-compiler` | 5.1.0 | Host serializer adapter |
+| `ajv-formats` | 3.0.1 | Installed host format plugin |
+| Vitest | 5.0.3 | Executable evidence |
+| TypeScript | 6.0.3 | Existing integration typecheck |
+
+Run the local checks from the repository root:
+
+```bash
+npm ci --cache tmp/cache/npm
+npx vitest run test/integration/content-model-gateway-feasibility.test.ts --reporter=verbose
+npm run typecheck:integration
+npm run docs:validate
+npm run test:conformance
+```
+
+The integration suite writes `tmp/conformance/content-model-gateway/traces.json`. Each ordinary probe records submitted JSON text, parsed submission, validator-visible values before/after, handler input, returned response, response-validation values, serializer-output values, status and actual HTTP bytes.
+
+Missing handler/serializer snapshots mean the request or response was rejected before that boundary. The imported current-emitter fallback has no body validator, so its trace records that boundary as absent rather than inventing validator observations.
+
+## Selected dialect boundaries
+
+### OpenAPI documentation
+
+Select OpenAPI `3.1.1` and its OAS schema dialect based on JSON Schema 2020-12 for future faithful documentation. Primary specification inspection establishes the standard; it does not prove that the installed Fastify runtime or serializer executes every OpenAPI keyword.
+
+The [current OpenAPI generator](../src/openapi/generateOpenAPI.ts) emits `openapi: "3.1.0"` and omits `jsonSchemaDialect`; this is source inspection, not an assertion that it already emits the selected `3.1.1` target. The synthetic complexity document in this probe uses `3.1.1` only to test gateway emission from that input.
+
+OpenAPI documents representation constraints and supplemental requirements. `x-xsd-fractionDigits` is an annotation: strict route-local Ajv rejects it as unknown; explicitly registering it as annotation-only admits `"1.234"` despite a declared value of two.
+
+### Runtime JSON Schema
+
+Select draft-07 for the bounded faithful runtime lowering. The installed default Ajv class loads the draft-07 vocabulary and meta-schema; the compiler uses `strict: true`, `coerceTypes: false`, `removeAdditional: false`, `useDefaults: false` and `allErrors: false`.
+
+Use route-level `validatorCompiler`; register referenced schemas with that Ajv instance explicitly. Do not change the host's global compiler or Ajv options. The same Fastify instance's control route retains coercion, default insertion and removal of unknown fields.
+
+Executed failures establish that a 2020-12 `$schema` cannot compile with this class and that unlabelled `unevaluatedProperties` fails strict compilation. Other modern vocabulary is outside the selected lowering; unknown required capabilities must fail planning or compilation rather than be ignored.
+
+### Serializer JSON Schema
+
+Select separately emitted draft-07 serializer schemas for the tested closed shapes. Installed `fast-json-stringify` documentation expressly requires draft-07 input; its conversion and branch selection behavior is not complete response validation.
+
+Validate returned HTTP JSON before serialization, validate parsed serialized bytes with the same independent runtime plan and shared semantic owner, and compare admitted JSON values for preservation. The probe's serializer wrapper rejects field loss before bytes leave Fastify; it does not repair the value or silently switch backend.
+
+Select an explicit route-local `JSON.stringify` fallback when serializer lowering cannot preserve an admitted JSON value or when the configured complexity policy selects fallback. Keep response validation and its references available regardless of serializer selection; a fallback must never remove the validation obligation.
+
+## Executed observations
+
+### Requests and host control
+
+| Case | Route-local observation | Host control observation |
+|---|---|---|
+| Numeric field submitted for string | 400; original field unchanged | Converted to string |
+| Required field with schema default missing | 400; field remains absent | Default inserted |
+| Unknown closed-object property | 400; property remains present | Property removed |
+| Both closed exclusive-choice fields | 400; both fields retained | 200 after removing one field |
+| Valid declared fields | 200; validator and handler values equal submission | Control remains independent |
+
+These observations prove that invalid input cannot pass only because validation coerces, inserts defaults or removes fields on the proposed route. They characterize existing Fastify defaults; they do not recommend a global host-policy rewrite.
+
+### Structural lowerings
+
+| Construct | Executed outcome | Boundary |
+|---|---|---|
+| Closed `oneOf` branches | Valid branch survives bytes; combined branches rejected | Runtime and schema serializer |
+| Overlapping `oneOf` | Both alternatives match; rejected | Runtime |
+| Overlapping `anyOf` | Both fields accepted and preserved | Runtime and JSON fallback |
+| Two empty `oneOf` alternatives | Empty object rejected because both match | Runtime |
+| Two empty `anyOf` alternatives | Empty object accepted and preserved | Runtime and JSON fallback |
+| Nullable array items | `["a",null]` accepted; null wrapper rejected | Runtime and schema serializer |
+| Nullable array wrapper | Null wrapper accepted; `[null]` rejected | Runtime and schema serializer |
+| Recursive `$ref` with nullable child | Nested valid response preserved; nested numeric value rejected | Runtime and schema serializer |
+| Outer object closure with `allOf` requirements | Both declared fields preserved; missing/unknown fields rejected | Runtime and schema serializer |
+| Closed disjoint `allOf` members | Original rejects `{a,b}`; current flattening accepts it | Current helper changes meaning |
+
+The draft-07 outer-closure fixture enumerates the complete property set once at its containing object and declares local properties in each required subschema to satisfy Ajv `strictRequired`. A graph-driven lowering must emit the equivalent complete closure; generic merging of arbitrary OpenAPI `allOf` is not an equivalence proof.
+
+An XML empty alternative is validated by the shared particle language, not by counting JSON `oneOf` matches. Overlapping or empty JSON alternatives that cannot express that language use a declared lowering plus #180 supplemental validation, with validated JSON fallback where serializer selection is unsuitable.
+
+### Scalar and facet boundaries
+
+Precision-sensitive int64 `"9223372036854775807"` and decimal `"9007199254740993.12345678901234567890"` survive validator snapshots and HTTP bytes exactly. Numeric substitutions and exponent-form decimal strings are rejected by the string representation schema.
+
+Submitting the same digits as JSON numbers loses precision in JSON parsing before the validator sees them. The native-number probe sees `9223372036854776000` and `9007199254740994`; downstream schema validation cannot restore the submitted digits.
+
+The reviewed lexical-sensitive witness `"+01.00"` survives response serialization. The fixture's anchored JSON pattern selects that representation and rejects `"1"`; it does not claim arbitrary XSD pattern equivalence or authorize rewriting a facet-constrained lexical witness.
+
+Representation-only validation admits `"9223372036854775808"` and decimal `"1.234"`. A separate test-only shared-owner callback uses built-in `BigInt` for int64 bounds and exact textual fractional digits after trailing-zero removal for a two-fractional-digit profile; it rejects upper/lower out-of-range and excess-scale witnesses before handler dispatch and before response serialization, without mutating values.
+
+The callback proves an executable supplemental seam, not a production XSD validator. Exact coefficient/scale conversion, totalDigits, all numeric bounds, XSD lexical/value normalization and XSD regex semantics remain owned by #184/#198; no duplicate scalar engine is added here.
+
+| Constraint | Independent Ajv evidence | Serializer evidence |
+|---|---|---|
+| `type`, `required`, object closure | Accepted and rejected cases | Approved closed fields preserved |
+| `pattern`, `minLength`, `maxLength` | Request and returned-response failures | Invalid string still serialized without independent validation |
+| Integer `minimum`, `maximum` | Request and returned-response failures | Out-of-range integer still serialized without independent validation |
+| `enum`, `minItems`, `maxItems` | Request and returned-response failures | Invalid array still serialized without independent validation |
+| Exact int64/fractionDigits | Supplemental callback rejects exact witnesses | Callback retained under JSON fallback |
+| `x-xsd-fractionDigits` | Unknown keyword rejected; annotation registration does not enforce | No enforcement claim |
+| XSD particle/regex/QName rules | Injected shared semantic seam only | No enforcement claim |
+
+### Response field preservation and complexity fallback
+
+An open object schema admits an `approved` field absent from `properties`. The schema serializer omits it, and the proposed preservation boundary returns 500 before output; explicitly selecting validated JSON fallback preserves the nested field and values.
+
+The current [gateway emitter](../src/gateway/generators.ts) selects no fallback at 149 reachable schema references and selects fallback at 150. The test imports the actual emitted route module and supplies a local handler for its generated stub; the route registration removes `response` and uses Fastify's JSON serialization fallback.
+
+That current emitted route returns both a valid 150-reference response and an invalid numeric/unknown-field response with 200 and unchanged bytes. The proposed adapter retains the same referenced runtime response schema, returns the valid response without field loss and rejects the invalid response before serialization even while using `JSON.stringify`.
+
+This broad 150-reference graph proves the existing policy boundary and fallback behavior. It does not measure the serializer's maximum depth, prove a stack overflow at exactly 150, or justify a new resource limit.
+
+## Decision-register handoff
+
+The following D06 entries resolve architecture choices within the tested scope. Missing implementation and qualification remain blocking gates for their first consumers; they are not claims of already shipped faithful behavior.
+
+| Entry | Selected contract | Evidence | First owner and consuming gate |
+|---|---|---|---|
+| D06-OpenAPI | OAS 3.1.1 documentation; separate runtime lowering | Primary standard; current output source inspected | #197 must emit selected dialect and completeness metadata |
+| D06-runtime | Strict non-mutating route-local draft-07 Ajv | Host isolation, structures, facets, modern-keyword failures | #198 validator/compiler plan; #199 request integration |
+| D06-serializer | Separate draft-07 serializer plan; serializer is not validation | Actual byte checks and ordinary facet counterexamples | #197 lowering; #200 preservation validation |
+| D06-fallback | Explicit JSON fallback preserves independent response validation | Imported current emitter and 150-ref proposed route | #200 must retain validation when serializer schema is omitted |
+| D06-supplemental | One shared #180/#184 semantic owner, injected at each boundary | Exact facet callback and fail-closed seam tests | #198 must supply shared rules; #199/#200 must invoke them |
+| D06-closure | Complete graph-derived closure; no generic allOf flattening | Original/flattened meaning differs | #197 lowering proof before #198/#199/#200 consume it |
+
+Required blockers are explicit: #197 must diagnose an unsupported lowering or choose an evidenced validated fallback; #198 must reject incomplete plans lacking required #180/#184 checks; #199 must validate before explicit representation conversion and dispatch; #200 must validate converted response JSON and serializer bytes before sending. Exact scalar facets, complete particle languages and lexical-sensitive normalization cannot be waived by schema or serializer success.
+
+## Documented and unverified combinations
+
+Installed primary docs describe draft-07, nullable extensions, recursive references, serializer defaults, field omission and branch selection. Documentation alone does not expand this finite executed corpus.
+
+Format plugins are installed on the host, but the route-local Ajv probe does not install them or claim date/time/binary format enforcement. QName namespace scope, XSD Unicode/regex differences, list/union assessment, wildcard and nil-with-attributes projections, mixed text, discriminator, `if/then/else`, dependent vocabulary and pathological recursive depth are unverified here and require implementing-issue fixtures.
+
+OpenAPI 3.1.1 document validation, generic 2020-12 Ajv compilation, arbitrary modern-to-draft-07 lowering, live network listeners, consumer-installed dependency matrices, Node 26 and adversarial performance/resource limits were not exercised by this integration suite. The current threshold remains a selected existing fallback policy rather than a newly measured engine limit.
+
+## Validation record
+
+The final targeted suite passed all 19 tests on Node 24.19.0; the existing integration typecheck passed. Full conformance passed all 138 tests across three files; documentation validation and the pipeline smoke check passed.
+
+IDE inspections were unavailable; repository-local TypeScript, Vitest and documentation checks provide the local verification. No production files, dependencies or global host options were changed.
+
+## Primary references
+
+- [Fastify 5.12.5 validation and serialization](https://github.com/fastify/fastify/blob/v5.12.5/docs/Reference/Validation-and-Serialization.md)
+- [Ajv 8.20.0 README](https://github.com/ajv-validator/ajv/blob/v8.20.0/README.md)
+- [Ajv 8.20.0 data modification](https://github.com/ajv-validator/ajv/blob/v8.20.0/docs/guide/modifying-data.md)
+- [fast-json-stringify 7.0.1 README](https://github.com/fastify/fast-json-stringify/blob/v7.0.1/README.md)
+- [OpenAPI 3.1.1 specification](https://github.com/OAI/OpenAPI-Specification/blob/3.1.1/versions/3.1.1.md)
+- [ADR 003 scalar profile](decisions/003-content-model-contracts.md#xsd-10-profile-and-enforcement-s02-d04)

package/docs/content-model-graph.md

@@ -0,0 +1,121 @@
+# Canonical Schema Graph
+
+Internal S04 graph contracts for the unreleased faithful compiler. See the root [README](../README.md).
+
+## Ownership and data flow
+
+[ADR-003 D01/D04/D09](decisions/003-content-model-contracts.md) defines identity, profile and budgets.
+[S03 loading](content-model-loading.md) supplies immutable syntax through its repository-owned adapter.
+[The model](../src/compiler/canonicalGraph.ts) and [pure builder](../src/compiler/buildCanonicalGraph.ts) implement #173.
+
+```text
+SchemaInput.schemas + ordered WSDL documents
+  -> reserve global symbols
+  -> build complete declarations and independent use sites
+  -> link available targets without expansion
+  -> freeze CanonicalGraph
+  -> S05 reference/composition assessment
+```
+
+`buildCanonicalGraph(input, {maxNodes?})` performs no I/O and never mutates input.
+The internal graph is not exported by the package entry point or activated by the CLI.
+The legacy compiler and its consumers retain the 1.x default.
+
+## Identities and immutable references
+
+Global IDs are JSON tuples `['global', role, effectiveNamespace, localName]`.
+Element, attribute, type, model group, attribute group and WSDL roles occupy separate symbol spaces.
+Simple and complex named types share the type symbol space.
+
+Scoped identity is `(containingDeclarationId, sourceRelativePath, role)`.
+The ID is `scoped:` plus SHA-256 of the UTF-8 JSON tuple `[owner, path, role]`; the tuple remains explicit in `identity`.
+Hashing prevents recursively escaped anonymous-owner IDs from growing exponentially with nesting.
+An anonymous type is a distinct type node owned by its containing declaration.
+Local elements with the same expanded name in different types retain independent declarations and type references.
+
+Syntax paths are relative to the containing declaration and preserve the adapter's ordered element/text indexes.
+They contain no document URI or temporary directory.
+Changing source structure may change scoped IDs; output names and prefixes never define identity.
+
+Interpretation keys live only in `origins`; repeated root/include interpretations do not create additional globals.
+Repeated declarations from the same byte digest and source path share one complete body.
+Conflicting declarations for one global identity fail explicitly rather than being merged by name.
+
+References are discriminated `symbol`, `builtin` or `local` values.
+Available global targets are linked after all bodies exist; unresolved symbol references keep their expanded name and lexical context with no target.
+S05 owns missing-target diagnosis, reference visibility, component-cycle legality and complete derivation semantics.
+
+For recursive `element Shared -> type Shared -> element-use Shared`, each target points to a complete declaration.
+No eager expansion or empty recursion placeholder is introduced.
+Two uses of group `Pair` with bounds `0..2` and `3..900719925474099312345678901234567890` share its definition and keep separate particles.
+
+## Node invariants
+
+Element and attribute declarations own their expanded names, type references and default/fixed constraints.
+Particles own only their local `Occurs` and term: ordered sequence, choice, legal XSD 1.0 all, element use, group use or wildcard.
+Attributes, attribute-group references and attribute wildcards occupy an ordered attribute-use list distinct from child content.
+
+Simple types retain restriction bases and ordered facets, list items or declaration-ordered union members.
+Complex types retain local content and attributes plus distinct extension/restriction edges and simple/complex content kind.
+No derived content, effective attribute composition or occurrence summary is calculated here.
+
+Finite bounds are canonical nonnegative decimal strings; `unbounded` is a distinct maximum token.
+The builder compares exact integers, rejects negative/fractional/reversed ranges and invalid all shapes, and never converts bounds to Number.
+Zero remains a local bound; S06 calculates its annihilating effect on summaries.
+
+WSDL nodes preserve ordered message/operation/binding/service syntax and role-qualified references.
+Their binding extensions, actions, body/header/fault selections and lexical attributes remain available to later planning.
+The graph does not select a SOAP transport or advertise qualified capabilities.
+
+## Lexical context and provenance
+
+Every graph node retains source URI, original-byte digest, source path and start/end positions, inherited base URI and namespace scope.
+Source offsets and exclusive ends follow the [adapter contract](content-model-loading.md#syntax-and-provenance-contract).
+`GraphContext.schemaAttributes` retains schema-level defaults for downstream interpretation.
+
+Facet values, defaults/fixed values, wildcard namespace constraints and explicit QName references retain `LexicalValue {value, context}`.
+Lexical values are not coerced, normalized or assessed by S04.
+QName facets can be interpreted later using the original locally rebound namespace context.
+
+Chameleon adoption changes a no-namespace component reference's effective target namespace while preserving its original lexical context.
+A lexical `Node` with an empty default binding can target `urn:a:Node` under adoption and `urn:b:Node` in another interpretation.
+An explicit/default lexical namespace remains authoritative; it is never overwritten by adoption.
+
+Default namespaces apply to lexical QNames and XML element names, while unprefixed ordinary XML attributes remain unqualified.
+Local declaration names use `form` or the schema's respective element/attribute form default.
+These declaration rules are independent of the XML syntax name's namespace.
+
+Annotations preserve ordered element/text syntax, attributes and namespaces, including mixed appinfo text.
+`syntaxDetails` preserves restriction/list/union and content-wrapper syntax; facets retain their complete declaring syntax.
+Known element-only XSD containers reject significant text explicitly, while mixed annotation content remains ordered.
+Uninterpreted declarations remain `retained` or contextual `schemaRetained` for S06 assessment; preservation is not support certification.
+Full internal URIs and loading edges remain provenance; [format 2 persistence](content-model-catalog.md) implements #174's artifact-safe serialization and semantic fingerprints.
+
+## Resource and validation boundaries
+
+The inclusive provisional limit is 100,000 declarations and use-site nodes together.
+An explicit positive safe-integer `maxNodes` overrides it; construction fails with `resource-limit` and returns no partial graph.
+Malformed structural shapes fail with `invalid-schema` and the declaring source.
+
+S03's loading limits and conservative cyclic-depth behavior are consumed unchanged in `graph.loading`.
+The builder performs structural checks only; S05 resolves/composes, S06 checks complete schema legality and reachable capabilities, and S07 matches values.
+UPA, scalar/facet legality, complete component-cycle rules and production codecs remain downstream gates.
+
+## Evidence and reproduction
+
+[Graph tests](../test/unit/canonical-graph.test.ts) reuse independent S01/S02 and S03 fixtures.
+[Graph fixtures](../test/conformance/fixtures/xsd/graph/shared-recursive.xsd) add shared definitions, recursion, local names, anonymous types, large bounds and scalar lexical context.
+[Chameleon input](../test/conformance/fixtures/xsd/graph/chameleon.wsdl) proves namespace adoption without rewriting lexical bindings.
+[Independent schema qualification](../test/conformance/reference/graph-contract.test.ts) preserves historical xmlschema 4.2.0 acceptance of the complete graph fixture. Current primary construction of the original huge bound remains unqualified under [NT-CONT-01](reference-validation.md), with exact scoped assertions and a separately hashed small copy.
+Historical libxml2 rejected that fixture's huge bound; the current adapter reports unsupported capability before engine allocation. The separate variant with maximum `4` constructs successfully; exact-bound assertions and archived xmlschema acceptance remain distinct from that fresh result.
+
+```bash
+npx vitest run test/unit/canonical-graph.test.ts test/unit/canonical-graph-budgets.test.ts
+npx tsc -p test/unit/tsconfig.json
+npm run ci
+npm run test:reference:full
+```
+
+[Budget evidence](../test/unit/canonical-graph-budgets.test.ts) measures 100,000/100,001 nodes and writes ignored results to `tmp/conformance/schema-graph/measurements.json`.
+The #151 handoff pins exact independently reviewed heads, merged revisions, commands/results and later qualification owners.
+Optional IDE checks, Windows filesystem behavior, private production schemas and broad platform limits remain unqualified.

package/docs/content-model-loading.md

@@ -0,0 +1,163 @@
+# Ordered Schema Loading
+
+Internal S03 input contracts for the unreleased faithful compiler. See the root [README](../README.md).
+
+## Ownership and compatibility
+
+[ADR-003 D01/D04/D09](decisions/003-content-model-contracts.md) owns the input, profile and budget decisions.
+The [decision register](content-model-decisions.md) assigns the later semantic consumers.
+The [ordered syntax adapter](../src/loader/orderedSyntax.ts) implements #171; [contextual traversal](../src/loader/schemaInput.ts) and [resource I/O](../src/loader/schemaResources.ts) implement #172.
+
+This internal adapter is not exported from the package entry point or activated by the CLI.
+The existing [WSDL loader](../src/loader/wsdlLoader.ts) remains the legacy default while #174 owns later routing.
+Parsing XML syntax does not certify XSD legality, resolve declarations, or establish payload validity.
+
+## Syntax and provenance contract
+
+`parseOrderedSyntax(bytes, absoluteUri, {maxDepth})` returns an immutable `SyntaxDocument` with `root`, full `uri` and SHA-256 `digest` of original bytes.
+`SyntaxElement.children` retains text and element order across every compositor kind; no name-keyed grouping occurs.
+Annotations, occurrence strings, declaration form settings and lexical attribute values remain available for their later owners.
+
+Each element retains its expanded `name`, `lexicalName`, ordinary attributes, all in-scope `namespaces`, effective `baseUri` and `source`.
+Namespace declarations populate context rather than ordinary attributes.
+Default namespaces apply to element names; unprefixed attribute names have an empty namespace.
+
+`resolveLexicalQName(value, element)` resolves QName-valued attributes or text in the declaring element's namespace context, including the default binding.
+It rejects malformed lexical names and unbound prefixes, without echoing lexical values in diagnostics.
+`syntaxElements` filters direct element children by expanded name while retaining order; `syntaxAttribute` retrieves an expanded attribute name.
+
+`source` contains full document URI, digest, stable source-relative syntax path and start/end positions.
+Lines and columns are one-based; offsets are zero-based UTF-16 positions in decoded XML and end offsets are exclusive.
+Syntax paths distinguish local declarations in different containing types; they are not global symbol identities.
+S04 owns global `(namespace, local, role)` identities and containing-declaration identities for locals.
+
+`baseUri` begins at the supplied final retrieval URI and inherits each `xml:base` through URL-reference resolution.
+For a document at `https://example.test/contracts/root.xsd`, `xml:base="../types/"` gives `https://example.test/types/`.
+The syntax adapter computes this context without performing I/O; #172 must authorize each resolved fetch.
+
+## Syntax limits and diagnostics
+
+The default nesting budget is 256 elements, inclusive, checked before accepting the next element.
+`SchemaLoadingError` distinguishes `invalid-schema`, `unsupported-capability`, `resource-limit` and `transport`; syntax errors carry source context.
+The adapter rejects DTDs, entity declarations and unresolved entity references, while accepting XML's predefined and numeric character references.
+
+UTF-8 and BOM-marked UTF-16 are decoded strictly; unsupported declared encodings fail explicitly.
+Comments and processing instructions are outside XML-value fidelity and omitted; CDATA retains its text.
+The parser dependency is confined to this module; consumers receive repository-owned types.
+
+## Controlled resolution contract
+
+`loadSchemaInput(source, {policy, limits, offlineResources})` creates one compilation-scoped snapshot.
+It accepts local paths, absolute file/HTTP(S) URIs, XSD roots and WSDL 1.1 definitions, including WSDL imports and inline schemas.
+It returns immutable documents, contextual schemas, resource metadata, explicit resolution edges, limits and I/O metrics.
+
+Traversal uses only expanded XSD include/import children and WSDL imports in their declaring syntax context.
+Payload roots fail with `unsupported-capability`; `xsi:schemaLocation` and annotation content never initiate resolution.
+Includes adopt the containing namespace only when the included schema has no target namespace; explicit namespace mismatches fail.
+Imports preserve their declared namespace and check it against the retrieved schema.
+
+An import without a schema location remains an unresolved edge for S05; it never guesses a network endpoint from its namespace.
+Include without a location fails as invalid input.
+Cycle edges remain in the result and stop active expansion; unresolved declaration diagnostics belong to S05 after traversal.
+
+Cached depth checks include inline schemas at zero edge cost and count the cycle-closing edge against current active ancestry.
+The [depth helper](../src/loader/resolutionDepth.ts) collapses strongly connected components and computes a polynomial upper bound on the condensed graph.
+Acyclic chains and closed simple cycles retain exact boundaries; cyclic components with branches or exits may exhaust this conservative budget earlier.
+An explicit caller depth override can admit them; no cycle edges or schema declarations disappear from the result.
+
+`SchemaInterpretation` exposes `syntax`, `documentUri`, `digest`, `baseUri`, `targetNamespace`, `context` and `key`.
+The context records root/inline/include/import kind and the namespace requested by that relationship.
+Its key is a deterministic tuple of digest, final document URI, effective base URI, effective target namespace, context kind/namespace and syntax path.
+The path distinguishes multiple inline schemas in the same document even when they share a namespace.
+
+For example, `common.xsd` without a target namespace included from `urn:a` and `urn:b` has one fetched resource and two interpretations.
+Both interpretations share immutable syntax; S04 reads their effective namespaces without changing lexical QName scope or mutating declarations.
+Identical bytes at `/base-a/common.xsd` and `/base-b/common.xsd` keep distinct interpretations because `child.xsd` resolves differently.
+
+The raw byte cache uses `(canonical final retrieval URI, SHA-256 digest)` and request/redirect aliases.
+Fetches and traversal are serialized within a compilation; each successful final resource is fetched once.
+The interpretation cache is separate and never keyed by digest alone.
+Previously authorized aliases reuse the compilation's pinned bytes without new filesystem or network I/O.
+Authorization I/O for a newly encountered file spelling still consumes the remaining deadline, even when it resolves to cached bytes.
+
+## URI and security policy
+
+`policy.fileRoots` authorizes local roots; `policy.allowedOrigins` authorizes exact HTTP(S) origins, including scheme and port.
+Both lists default to empty. No input root grants implicit import permission.
+Every import and redirect is rechecked, including the result of inherited `xml:base`.
+
+HTTP redirects are manual and policy-checked before the next request; an HTTP redirect cannot select a file.
+The final checked URI becomes document identity and the initial base for syntax.
+Origin policy authorizes the destination explicitly, including any caller-approved private destination; it does not inherit application transport credentials.
+
+URL normalization removes fragments, resolves dot segments and normalizes host/default-port spelling while preserving queries.
+Local paths become absolute file URIs; filesystem identity uses `realpath`, with traversal and symlink checks against configured roots.
+File queries and remote file authorities, other schemes and URLs containing user/password credentials fail explicitly.
+
+Full source URIs are internal provenance, not semantic fingerprints or publishable artifact fields.
+Callers must use credential-free source URLs and trusted, stable authorized filesystem roots; S04/#174 owns artifact-safe provenance serialization.
+Transport errors omit upstream response text and credential-bearing error strings; referencing-node source locations remain available.
+
+An optional offline map contains canonical URIs and pinned `{bytes, digest}` records.
+Every offline resource still passes policy, size and digest checks; a missing record fails without network fallback.
+Resource metadata exposes full final URI, digest and decompressed byte length, with no raw bytes in the returned input snapshot.
+
+## Loading budgets
+
+The provisional defaults from ADR-003 are implemented before downstream graph construction.
+Positive safe-integer overrides permit explicit caller increases or lower limits; redirects may be zero.
+
+| Budget | Inclusive default | Outcome beyond limit |
+|---|---|---|
+| Distinct final resources | 128 | `resource-limit` before new final body |
+| Decompressed resource bytes | 8 MiB | `resource-limit` before parse |
+| Aggregate decompressed bytes | 64 MiB | `resource-limit` before parse |
+| Resolution depth bound | 32 edges | `resource-limit`, including cached subtrees |
+| Redirects per fetch | 5 | `resource-limit` before sixth destination |
+| Resource I/O | 15,000 ms | `transport`, abort/cancel input |
+| Total compilation I/O | 120,000 ms | `transport`, abort/cancel input |
+| XML element nesting | 256 | `resource-limit` in syntax adapter |
+
+HTTP response bodies and files are read incrementally; decompressed chunks count against both byte budgets.
+At the resource-count limit, bounded HTTP redirect discovery may still identify a cached final resource; a new final body is cancelled.
+Local special files are rejected before opening; nonblocking/no-follow open flags and a descriptor check guard the final file boundary.
+The deadline covers fetching, redirects and body reads; parsing is outside the I/O clock.
+The total counts serial resource I/O, with monotonic timing and the remaining total budget constraining each fetch.
+No rejected load returns a partial schema model.
+
+## Evidence and reproduction
+
+[Ordered syntax tests](../test/unit/ordered-syntax.test.ts) reuse independently qualified S01 compositor and S02 ordered SOAP inputs.
+[Syntax fixtures](../test/conformance/fixtures/xsd/syntax/ordered-namespaces.xsd) and their [default-namespace equivalent](../test/conformance/fixtures/xsd/syntax/default-namespaces.xsd) exercise interleaving, annotations, rebinding, lexical QNames and distinct local paths.
+These syntax fixtures establish input preservation; later graph/profile tasks own semantic schema assessment.
+
+```bash
+npx vitest run test/unit/ordered-syntax.test.ts --reporter=verbose
+npx tsc -p test/unit/tsconfig.json
+npx vitest run test/unit/schema-input.test.ts test/unit/schema-loading-budgets.test.ts test/integration/schema-resource-http.test.ts
+npm run ci
+```
+
+Depth 256 succeeds and depth 257 fails with `resource-limit`; lower configured limits and malformed XML fail explicitly.
+Tests also preserve the legacy relative-import fixture and validate source locations/digests and strict byte decoding.
+Exact reviewed commits, executed aggregate results and measured limits are recorded in #150's final S03 handoff.
+
+[Context fixtures](../test/conformance/fixtures/xsd/resolution/chameleon.wsdl) add chameleon/repeated includes, identical-byte bases, relative chains and cycles.
+[Context tests](../test/unit/schema-input.test.ts) add offline digests, namespace mismatch, URI policy, query identity, symlink/traversal rejection, WSDL imports and payload hints.
+[Live HTTP evidence](../test/integration/schema-resource-http.test.ts) checks final retrieval/base resolution and actual gzip decompression.
+
+[Budget tests](../test/unit/schema-loading-budgets.test.ts) run 128/129 resources, 8 MiB/8 MiB+1, 64 MiB/64 MiB+1, 32/33 edges, 5/6 redirects and 256/257 syntax depth.
+Per-resource 15,000/15,001 ms and total 120,000/120,001 ms use controlled monotonic clocks, with stalled-body cancellation also checked.
+They write observed outcomes and elapsed times to ignored `tmp/conformance/schema-loading/measurements.json`.
+These boundary measurements do not qualify production network latency, private vendors, Windows filesystem behavior or general supported maxima; #208 owns later qualification.
+
+## S04 continuation inputs
+
+#171 was independently reviewed at `3bb3cd656b1c0d15906d55262a22776c78964984` and merged normally through PR #225 as `11f635072ee0999cd5f904c58cae90b476b064ff`.
+#172 starts from that merge and consumes its exact syntax contract.
+The final #150 acceptance record pins both reviewed heads, merge revisions, full repository checks and merged-main checks.
+
+S04 #173 reads `SchemaInput.schemas` and the immutable ordered syntax, deriving global identities from effective namespace, local name and role.
+Scoped local identities use containing declarations and source-relative paths; interpretation context remains resolution/provenance data.
+#174 serializes artifact-safe provenance separately from semantic fingerprints and implements catalog routing.
+S05 resolves declaration/reference semantics from the recorded edges; S03 does not create canonical graph nodes, projections or codecs.

package/docs/content-model-matching.md

@@ -0,0 +1,85 @@
+# Direct structural matching
+
+Internal authenticated payload structure and scalar handoff contract. See the root [README](../README.md).
+
+## Authority and supported grammar
+
+[matchDirectOperation](../src/compiler/directStructure.ts) consumes an issued [DirectOperationContract](../src/compiler/directOperation.ts), a `DirectDirection` and an ordered `SyntaxElement` payload. `inspectDirectOperation` supplies the exact original source/context/root; copies and diagnostic JSON throw `TypeError`. There is no root/context override, source reload, cache, public export or runtime admission.
+
+Directions are `{kind: 'input'}`, `{kind: 'output'}` and `{kind: 'fault', name: string}` for an exact declared fault. Unknown directions/faults return `unsupported`. The source gate remains the unchanged [P1-D01](decisions/003-content-model-contracts.md#checked-product-assessment-amendment-p1-d01) sufficient direct correspondence route.
+
+The matcher handles global string/int/boolean scalar roots and named element-only complex roots containing a flat ordered sequence of distinct scalar declarations, including empty sequences. Native declaration names determine namespace/form; native occurrence pairs have minima `0`/`1` and maxima `1`/`unbounded`. It consumes original particles and the shared occurrence algebra, never interval summaries as a language validator.
+
+A monotone cursor and actual occurrence count enforce order, required members, singleton maxima and complete consumption. Advancing a slot prevents returning to it later. Unbounded repetition consumes only actual input, with no maximum expansion or speculative state allocation.
+
+## Results and retained duties
+
+`structural-match` has `scope: 'structure-only'`, `scalarValidity: 'unassessed'` and `admitted: false`. It retains the exact `root`, `contextId`, owned `direction`, ordered `occurrences` and final `usage`. It never changes the original contract's `admitted` or `missingCapabilities` fields.
+
+Every `DirectScalarDuty` retains the actual immutable `declaration`, its exact `type` reference, `builtin` expanded name, complete `lexical` text, owned payload `namespaces` and `payloadSource`, generated `payloadPath` and native `schemaPath`. Empty text differs from an absent required element. Text fragments are concatenated without trimming, normalization, conversion or default insertion.
+
+`mismatch` covers wrong expanded names, order/count/consumption, significant element-only text and nested scalar elements. Only XML whitespace (`#x20`, `#x9`, `#xD`, `#xA`) is ignored between complex children. Ordinary attributes, `xsi:nil`, `xsi:type` and `xml:*` return `unsupported` because their semantics are unimplemented; namespace declarations reside in namespace context and are permitted.
+
+`cancelled` and `resource-limit` carry no partial match. Diagnostics carry fixed rules, source schema paths and generated numeric payload paths, without echoing lexical values or caller-supplied paths. Malformed data throws `TypeError`; a potentially legal unsupported payload feature is never called invalid schema.
+
+## Input ownership and resource lifetime
+
+Inputs are data-only plain records and dense arrays, without proxies or accessors. A prepass checks the element root and rejects reused/cyclic syntax nodes through descriptors without invoking getters, reserving syntax nodes before copying. An iterative budgeted snapshot owns retained payload facts; shape checks then distinguish malformed records from XML structural differences. Caller/source objects are neither modified nor newly frozen.
+
+The original selected context budget charges planning, syntax visits, descriptor inspection, text/maps, copying, paths, occurrence collection, freezing and final publication. Repeated calls share the remaining sticky budget; failure cannot reset it. Node accounting adds each payload element/text node to the cumulative source-preparation/context count, and work also bounds all auxiliary records.
+
+Traversal terminates because preflight rejects cyclic/reused syntax nodes, snapshot uses an explicit identity stack, and matching advances through finite payload children and schema slots. Work and retained memory scale with the actual source plan and payload facts, including text/maps/provenance; publication also traverses the retained native root graph. No operation scales with an unbounded hypothetical cardinality.
+
+Cancellation is checked at entry, schema/payload visits, matching boundaries and before publication. This synchronous operation cannot observe timer callbacks until JavaScript yields; it claims cooperative checks only. A reusable production client's invocation-budget lifecycle requires a separate design decision.
+
+## Repository-local example
+
+Run the following from the repository root using `node --import tsx --input-type=module-typescript` and standard input. Parsing here supplies a payload tree for demonstration, not a production SOAP adapter or security qualification.
+
+```typescript
+import path from 'node:path';
+import {selectDirectOperation} from './src/compiler/directOperation.ts';
+import {matchDirectOperation} from './src/compiler/directStructure.ts';
+import {parseOrderedSyntax} from './src/loader/orderedSyntax.ts';
+
+const namespace = 'urn:checked:forecast';
+const selected = await selectDirectOperation(
+  'test/conformance/fixtures/assessment/forecast.wsdl',
+  {portType: {namespace, local: 'ForecastPortType'},
+    binding: {namespace, local: 'ForecastBinding'}, operation: 'GetForecast'},
+  {loading: {policy: {fileRoots: [path.resolve('test/conformance/fixtures/assessment')]}}},
+);
+if (selected.kind !== 'selected') throw new Error(selected.kind);
+const cases = [
+  {direction: {kind: 'input'} as const,
+    xml: '<f:GetForecast><f:city>Paris</f:city><f:days>not-an-int</f:days></f:GetForecast>'},
+  {direction: {kind: 'output'} as const,
+    xml: '<f:GetForecastResponse><f:city>Paris</f:city><f:complete>true</f:complete></f:GetForecastResponse>'},
+  {direction: {kind: 'fault', name: 'ForecastError'} as const,
+    xml: '<f:ForecastFault><f:code>NOT_FOUND</f:code><f:message>Unknown city</f:message></f:ForecastFault>'},
+];
+for (const example of cases) {
+  const xml = example.xml.replace('>', ` xmlns:f="${namespace}">`);
+  const payload = parseOrderedSyntax(Buffer.from(xml), 'https://payload.invalid/message.xml').root;
+  const result = matchDirectOperation(selected.contract, example.direction, payload);
+  console.log(result.kind, result.kind === 'structural-match' ? result.scalarValidity : result.rule);
+}
+```
+
+All three print `structural-match unassessed`, including the intentionally invalid int lexical witness. No SOAP endpoint is contacted. This matching-only example does not assess SOAP envelopes/faults, parser security, scalars, projection/byte round trips, transport or generation; the separate value/codec consumer below supplies its own named checks.
+
+## Independent evidence
+
+[Independent language tests](../test/unit/direct-structure-evidence.test.ts) specify Forecast request/response/fault expectations without the subject plan. The test-only adapter uses exact SOAP namespace/path extraction. Literal mutations cover trailing requirements, late returns, namespaces/forms, renamed sources, scalar roots, empty sequences, text and attributes.
+
+Finite enumeration covers 1,444 words: 40 request words of length 0..3 over city/days/alien, 341 response words of length 0..4 over city/temperature/complete/alien for each of four temperature occurrence pairs, and 40 words for city-star/days-star. Literal language predicates independently determine expectations; these are finite corroboration, not universal XSD completeness. [Ownership/resource tests](../test/unit/direct-structure.test.ts) cover authority, immutable facts, malformed/cyclic/accessor input, inclusive work/node boundaries, cancellation and sticky reuse.
+
+## P3.3 scalar consumption and fresh inverse
+
+The matcher now registers only its actual final successful returned object after final cancellation/resource checks. `inspectDirectStructuralMatch(match, expectedContract)` authenticates identity before reading receipt fields; copied/JSON/zero-duty and foreign-contract objects fail. Existing unregistered historical results cannot authenticate retrospectively. The registry binds exact operation, context, root and owned direction because those are immutable fields of the issued object.
+
+[Direct scalar values](direct-values.md) documents the implemented payload facade, complete source-derived mapping, fresh inverse, normalization laws, independent review and internal bounded XML codec. The native slot helper is shared by matcher and mapping; absent optional and zero-count repeated fields cannot disappear from the plan. Scalar success is separate from this matcher's unchanged structure-only result and still grants no runtime admission.
+
+The new direct value chain retains original lexical/map/source/type evidence, validates through neutral shared datatype calculations and revalidates generated lexical data through matching and scalar assessment. No schema operand receipt or provenance is fabricated. The [accepted resource model](direct-values.md#accepted-resource-model) precharges the source-known valid key vector and explicitly excludes oversized engine-internal vectors from malformed objects; it makes no all-V8-allocation or hard heap bound claim.
+
+Nil, attributes/type overrides, augmentation/defaults, arbitrary derivation and general conversion remain unsupported. The internal [bare-root XML codec](direct-values.md#internal-bare-root-xml-codec) consumes this matcher without changing its receipts. Transport, persisted bundles, public structured activation and generation remain deferred; defaults/version and publication status are unchanged. Broader matcher/evidence owners remain open beyond this direct slice.