@techspokes/typescript-wsdl-client 1.1.3 → 1.1.5

package/docs/content-model-baseline.md

@@ -0,0 +1,121 @@
+# Content Model Baseline
+
+Bounded S01 evidence for current output and independent XSD 1.0 validation. See the root [README.md](../README.md) for documentation navigation.
+
+## Purpose and boundary
+
+[Task #166](https://github.com/TechSpokes/typescript-wsdl-client/issues/166) characterizes the finite corpus agreed in [S01 #148](https://github.com/TechSpokes/typescript-wsdl-client/issues/148). It preserves the shipped #141 correction and public defaults; remaining semantic repairs belong to [epic #147](https://github.com/TechSpokes/typescript-wsdl-client/issues/147).
+
+The source baseline is main at `b633cd1561ccb2689134a7289cf48bb097b0d1f1`, with package v1.1.4, TypeScript 6.0.3 and Node 24.19.0. The runner reports the actual checked-out commit and tracked dirty state separately from this production baseline; PR and issue acceptance records pin the final tested delivery commits.
+
+## One authoritative manifest
+
+[`semantic-baseline.json`](../test/conformance/semantic-baseline.json) owns the 14 case IDs, inputs, expected reference outcomes, current generated behavior, intended semantics and gap disposition. Each case links a capability in the existing [registry](../test/conformance/registry.ts); the two new research rows record limitations rather than increasing supported-feature claims.
+
+The corpus reuses the [occurrence fixture](../test/conformance/fixtures/xsd/sequences/sequence-occurrence-wrappers.wsdl) from the public #141 example and the existing [simple-choice fixture](../test/conformance/fixtures/xsd/compositors/choice-union-simple.wsdl). The [boundary fixture](../test/conformance/fixtures/xsd/compositors/content-model-boundaries.wsdl) adds legal minimal cases, while [invalid-all](../test/conformance/fixtures/xsd/compositors/content-model-invalid-all.wsdl) preserves a historical illegal input with an explicit schema-rejection disposition.
+
+### Manifest fields
+
+| Field | Meaning |
+|---|---|
+| `id`, `family` | Stable case and bounded semantic family |
+| `capabilityId`, `fixture`, `provenance` | Existing registry link and sanitized source |
+| `findings` | Stable CM identifiers from epic #147 |
+| `schema` | Expected independent schema-compilation outcome |
+| `instances` | Committed XML inputs and expected reference outcomes |
+| `current` | Observed catalog, scoped TypeScript and OpenAPI assertions |
+| `current.defaultChoice` | Separate current default-mode assertions for choices |
+| `intended` | Desired schema meaning, not production expectations |
+| `disposition` | Remaining gap and numbered downstream owners |
+| `downstream` | Real transport, registry mock, unrun or inapplicable evidence |
+| `referenceDisagreement` | Explicit validator disagreement and resolution owner |
+| `fast` | Membership in the required deterministic subset |
+
+All fixture paths are relative to `test/conformance/fixtures/`. Current OpenAPI assertions use `flattenArrayWrappers: false` to expose the element properties; the existing occurrence transport suite separately exercises both wrapped and flattened HTTP responses.
+
+The [characterization suite](../test/conformance/semantic-baseline.test.ts) compiles the fixtures and compares current catalog/type/schema results with literal manifest expectations. Choice cases execute opt-in `union` and current default `all-optional` independently; neither mode's name serves as evidence of its behavior.
+
+## Setup and reproduction
+
+Node 24 or 26 and npm provide reference qualification through pinned test-only `libxml2-wasm@0.7.2` and libxml2 2.15.1. [NT-CONT-01](reference-validation.md) retains fresh scoped TypeScript checks and historical xmlschema observations separately; it does not claim two live general-purpose validators.
+
+Run setup once with package-index access, then validation requires only committed inputs and installed tools. No production dependency or runtime validator is introduced.
+
+```bash
+npm ci --cache tmp/cache/npm
+npm run reference:setup
+npm run test:reference
+npm run test:reference:full
+npx vitest run test/conformance/semantic-baseline.test.ts test/integration/sequence-occurrence-transport.test.ts
+npx tsc -p test/conformance/tsconfig.json
+```
+
+`reference:setup` checks the installed package version and executes a schema-construction control. Normal `npm ci` installs the prebuilt artifact; no interpreter environment or activation is needed.
+
+The engine remains a development dependency outside generated consumer artifacts. Reports stay under `tmp/conformance/reference`; ordinary pipeline resets remove only `tmp/smoke`.
+
+### Required and full lanes
+
+`npm run test:reference` runs six deterministic cases and 15 instances: original-sequence, simple-choice, sequence-order, zero-group-unbounded, finite-count-gap and invalid-all-sequence. Node 24/26 CI requires this command, the toolchain guard and scoped strict TypeScript checks.
+
+`npm run test:reference:full` executes all 14 schemas and 40 instances, including the selected contract and historical secondary answer for the disabled-element disagreement. Both selections execute all 53 mapped methods and reject missing execution; setup, input, version and observation failures exit nonzero.
+
+The launcher also exercises setup/input/schema failures, observation disagreements, offline boundaries and resource limits. Unit controls reject unsupported Node versions, empty discovery and failed test commands.
+
+The launcher writes machine-readable evidence and actual executed-method traceability automatically:
+
+```bash
+npm run test:reference:full
+```
+
+## Reference adapter responsibilities
+
+The [Node adapter](../test/conformance/reference/adapter.ts) extracts one embedded schema and materializes inherited namespace bindings before compiling it. This preserves prefixes used only in QName-valued attributes, such as `type="tns:AddressType"`; losing those bindings would manufacture schema failures.
+
+libxml2 supplies primary schema and instance results without importing production semantic helpers. Expected results are literal independent assertions in the manifest, not computations from catalog bounds.
+
+The adapter rejects DTDs, unknown external resources and path escapes, and confines inputs to the committed fixture root. Composition requires an explicit local registered resource set; broader schema loading remains with downstream owners.
+
+Schema compilation and instance validation have separate output fields. A rejected schema produces no instance results; malformed or missing inputs and missing tooling are setup/input failures rather than expected instance rejection. Successful qualification means recorded observations agree, including explicitly assigned disagreements; it does not prove the future faithful model is implemented.
+
+## Executed outcomes
+
+Full qualification covers 14 cases: 13 schema-accepted cases, one schema-rejected case and 40 primary instance checks. These span four distinct WSDL fixtures and report each case independently. The required subset covers six cases and 15 instances.
+
+The illegal nested sequence beneath `xs:all` fails schema compilation before instance evaluation. Its legal optional-all counterpart accepts the empty group and a single item, and rejects two items; production output still requires the item.
+
+### Validator disagreement
+
+For `zero-element-unbounded`, historical libxml2 2.14.6 and current 2.15.1 accept both the empty instance and the disabled `row`. Historical xmlschema 4.2.0 rejects the row; the fresh scoped rule also rejects it from its original `maxOccurs=0` source. The runner labels these distinct evidence kinds and leaves fresh full second-engine validation unqualified.
+
+The primary `accepted` expectation characterizes libxml2's limitation, not valid XSD semantics. [#181](https://github.com/TechSpokes/typescript-wsdl-client/issues/181) owns reference-oracle follow-up under CM-15, while schema analysis, matching and projection owners retain the implementation gap. Do not use primary acceptance here to approve a future codec.
+
+## Consumer evidence and limitations
+
+The [real SOAP transport test](../test/integration/sequence-occurrence-transport.test.ts) and [shared harness](../test/helpers/occurrenceTransport.mjs) verify singleton and two-item response arrays, omitted optional requests, repeated bounded/unbounded request XML and gateway JSON bytes after serialization. Both wrapper-flattening modes execute, and installed-package smoke reuses this harness.
+
+This proves the focused occurrence shape correction and singleton normalization, not complete XML-instance validation. Other boundary cases have catalog/type/OpenAPI evidence only unless their manifest explicitly links registry mock evidence; no production vendor WSDL or later buffered/streaming architecture probe is claimed.
+
+Finite lengths and the 2-or-4 count hole remain unenforced in generated arrays. Repeated `(a,b)` sequence order and group correlation are lost in independent property arrays. Disabled groups, optional all, inherited choice bounds, repeated selections and empty alternatives retain current limitations.
+
+Current default choice output requires scalar fields for the selected minimal fixtures, while opt-in union expresses a single exclusive branch. A required repeated choice needs two selections, potentially of the same branch; neither current representation captures that language.
+
+Wildcard metadata retains local bounds, but the current TypeScript/OpenAPI projection omits ordered wildcard elements and enclosing repetition. These are characterization results, not new supported-pattern claims.
+
+## Downstream ownership and S02 inputs
+
+Each manifest disposition records concrete issue numbers. Subsequent consumer qualification owns the applicable client/gateway behavior; the existing public [support matrix](supported-patterns.md) remains authoritative for released claims.
+
+| Responsibility | Owning issue |
+|---|---|
+| Bounds, choice presence and count analysis | [#178](https://github.com/TechSpokes/typescript-wsdl-client/issues/178) |
+| Schema legality and reachable support | [#179](https://github.com/TechSpokes/typescript-wsdl-client/issues/179) |
+| Ordered particle matching | [#180](https://github.com/TechSpokes/typescript-wsdl-client/issues/180) |
+| Independent oracle disagreement | [#181](https://github.com/TechSpokes/typescript-wsdl-client/issues/181) |
+| Reversible value and branch projection | [#182](https://github.com/TechSpokes/typescript-wsdl-client/issues/182) |
+| Faithful XML encoding | [#188](https://github.com/TechSpokes/typescript-wsdl-client/issues/188) |
+| HTTP representation validation | [#198](https://github.com/TechSpokes/typescript-wsdl-client/issues/198) |
+
+[S02 #149](https://github.com/TechSpokes/typescript-wsdl-client/issues/149) must decide how ordered/group-correlated data is represented, what XML equivalence means for invisible groups and empty branches, and how the declared XSD/datatype/wildcard profile is enforced. It must assign validation versus normalization and serialization boundaries, compatible artifact routing, public activation policy and bounded resource failures.
+
+These are inputs to [#168](https://github.com/TechSpokes/typescript-wsdl-client/issues/168), not an S01 architecture implementation. The SOAP and gateway feasibility probes remain blocked until a reviewed ADR draft supplies their concrete contracts.

package/docs/content-model-catalog.md

@@ -0,0 +1,116 @@
+# Semantic Catalog Format 2
+
+Internal S04 persistence and compatibility boundaries for the unreleased faithful compiler. See the root [README](../README.md).
+
+## Versions and entry points
+
+[ADR-003 D04/D09/D10](decisions/003-content-model-contracts.md) and the [decision register](content-model-decisions.md) own profile, budgets and compatibility.
+[The graph contract](content-model-graph.md) remains authoritative; a compatibility view is always derived.
+[Catalog entry points](../src/compiler/semanticCatalog.ts) are internal modules, outside the package entry point.
+
+`SemanticCatalog` contains `catalogFormat: 2`, `model: "xsd10-faithful-v1"`, `profile: "xsd10-faithful-v1"`, `graph` and `semanticFingerprint`.
+`createSemanticCatalog(graph, limits?)` creates an immutable portable snapshot.
+`serializeSemanticCatalog(catalog, limits?)` emits canonical JSON and one trailing newline.
+`readCatalog(text, {mode?, maxBytes?, maxDepth?, maxNodes?})` returns a discriminated legacy, semantic or regeneration-required result.
+`readCatalogFile(file, options)` applies the same boundary through a bounded regular-file read and strict UTF-8 decoding.
+`readLegacyCatalogFile` is the explicit adapter used by existing CLI, OpenAPI, gateway, app, generated-test and companion-catalog readers.
+
+No new faithful CLI flag, public export or emitter is activated.
+Source compilation through `prepareCompilationInput` defaults to the existing legacy loader/compiler and preserves legacy names/options.
+An explicit internal `mode: "faithful"` builds only the ordered graph/catalog through [S03 loading](content-model-loading.md), with caller-authorized policy.
+It does not certify support or produce the later portable bundle.
+
+## Canonical persistence and validation
+
+Object keys use ECMAScript UTF-16 code-unit ordering and compact JSON encoding.
+Node/global display tables sort by ID; origin tables sort by their canonical representation.
+Particle children, union members, facets, attributes, ordered syntax and WSDL reference arrays retain their declaration order.
+The reader normalizes display tables, so accepted permutations serialize identically.
+
+Global IDs are compact JSON tuples from the graph contract.
+Scoped IDs hash UTF-8 bytes of compact `JSON.stringify([owner, path, role])`, with JSON string escaping and no whitespace.
+For `owner = "parent"`, `path = "/0/1"`, `role = "type"`, the input bytes encode `["parent","/0/1","type"]` and the ID is `scoped:f325bc3d3205fbca17c95034c3a1093ed14ce66b9db6347931ad6890c026f65f`.
+The explicit identity tuple remains serialized for verification by another language.
+
+Finite bounds remain exact canonical unsigned decimal strings; `unbounded` is a distinct maximum.
+Every discriminant, required field, node identity, index, reference role/target, QName namespace context and structural ownership is checked before returning an immutable catalog.
+Scoped structural use sites have one parent; semantic references can share declarations and recurse.
+Containment/ownership cycles, malformed bounds, nested all, illegal all children, empty unions, unknown mandatory fields and duplicate JSON keys fail explicitly.
+WSDL reference indexes must agree with the ordered declaring syntax, lexical scope and source context.
+Validation of complete derivation/reference visibility, facet legality, UPA and supported capabilities remains with S05/S06.
+
+## Provenance and fingerprints
+
+Internal graph retrieval URIs never become global or scoped identity.
+Portable source locations retain digest, source path and exact start/end positions with `urn:source:sha256:<original-byte-digest>`.
+Inherited bases and loading-reference URIs use `urn:base:sha256:<digest>` tokens.
+Same-resource bases hash source digest, document-relative placement and an optional query digest; relocating the complete fixture tree does not change catalog bytes.
+Interpretation tuples retain namespace/adoption/resolution distinctions using portable source/base tokens, independently of symbol identity.
+The reader rejects raw retrieval provenance rather than silently redacting an input artifact.
+
+Retrieval attributes such as `xml:base`, schema locations and documentation source URIs become digest tokens.
+Binding endpoint addresses remain ordered semantic syntax; credential-bearing URI userinfo and recognizable secret query parameters on binding addresses are rejected.
+Credentials belong to external runtime configuration.
+No serialization can infer secrets embedded in arbitrary schema text: input annotations/lexical values must be suitable for the intended artifact audience.
+
+The SHA-256 semantic fingerprint excludes source digests/locations, retrieval bases, loading policy/edges, origin tables, documentation and annotations.
+Reference fingerprints use expanded role-qualified names, rather than prefix spelling, while the artifact preserves original lexical QName context for validation and later interpretation.
+Fingerprint-only scoped IDs follow ordered structural containment; serialized source-relative identities and WSDL syntax paths remain unchanged.
+This keeps inserted documentation and element-only formatting whitespace out of semantic identity without changing semantic child order.
+Remaining scalar/facet/default/fixed lexical values and namespace context participate conservatively; S04 does not assert datatype equivalence.
+The fingerprint detects semantic mismatch, not authenticity or provenance tampering; this is not the later bundle fingerprint combining projections/binding/capabilities/scope.
+#185/#186 own bundle format 1 and integrated compatibility checks.
+
+## Early compatibility matrix
+
+| Input / selected mode | S04 behavior |
+|---|---|
+| Legacy unversioned catalog / legacy | Explicit legacy adapter; retain existing metadata, names and options |
+| Legacy catalog / faithful | Regeneration-required, category `incompatible-artifact`, original source required |
+| Original WSDL / legacy | Existing loader/compiler; default unchanged |
+| Original WSDL/XSD / internal faithful | Controlled ordered loader, immutable graph and format 2 catalog only |
+| Format 2 catalog / internal faithful | Typed validation, exact version/model/profile and fingerprint check |
+| Format 2 catalog / legacy consumer | Reject `incompatible-artifact`; regenerate matched legacy artifacts from original source |
+| Unknown format/model/profile, versioned bundle at catalog boundary | Reject explicitly; no fallback to the flattened reader |
+| Mixed generated artifacts or faithful OpenAPI-only gateway | Deferred to #185/#186/#195/#196/#201; require the original source and portable bundle |
+
+The legacy reader checks the historical envelope and named table entries without inventing missing ordered structure or renaming metadata.
+Its compatibility boundary is not a new complete validator for every historical compiler field.
+The regeneration result supplies the internal source-compilation call, with placeholders for the original source and authorized roots.
+For example, import `prepareCompilationInput` in a repository development program and call:
+
+```typescript
+await prepareCompilationInput(
+  {kind: "source", source: originalSource},
+  {mode: "faithful", loading: {policy: {fileRoots: authorizedRoots}}},
+);
+```
+
+The shipped `wsdl-tsc compile` command still emits the legacy catalog.
+There is no supported faithful generation command during S04.
+The architecture release train remains 2.0.0, with integrated S17/S18 evidence and separately approved default activation.
+
+## Limits, evidence and downstream readiness
+
+The catalog boundary defaults to 64 MiB of UTF-8 JSON, 100,000 graph nodes and JSON nesting depth 1,024, inclusive.
+Byte/node overrides require positive safe integers; nesting can be lowered but cannot exceed the reader safety ceiling.
+Configured byte boundaries, multibyte input, node rejection, 1,024/1,025 nesting, corrupt UTF-8 and Linux FIFO rejection have executable tests.
+The full default 64 MiB catalog boundary and Windows special-file behavior are not platform-qualified by these tests.
+S03 loading limits, denial defaults and conservative cyclic-depth behavior are consumed unchanged.
+Later scalar/projection/codec budgets retain their [assigned owners](content-model-decisions.md).
+
+[Catalog tests](../test/unit/semantic-catalog.test.ts) reuse independent graph, chameleon and SOAP fixtures and cover relocation, lexical facets, large bounds, recursion, corrupt artifacts and consumer rejection.
+[Independent graph schema evidence](../test/conformance/reference/graph-contract.test.ts) retains the historical xmlschema/libxml2 large-bound distinction and explicit current qualification limits under [NT-CONT-01](reference-validation.md).
+
+```bash
+npx vitest run test/unit/semantic-catalog.test.ts test/unit/canonical-graph.test.ts
+npx tsc -p test/unit/tsconfig.json
+npm run ci
+npm run test:reference:full
+```
+
+#151's final handoff pins reviewed heads, merge revisions, versions, fixtures, exact commands/results and S05 readiness.
+#175 resolves references, #176 implements derivation/attribute composition, and #177 integrates companion closures and diagnostics.
+#178 owns later occurrence summaries.
+S02's open streaming/incoming-security qualifications and S01's #181-owned oracle disagreement remain downstream gates.
+Production codecs, projections, emitter rewrites, package publication and default activation remain outside S04.

package/docs/content-model-companions.md

@@ -0,0 +1,90 @@
+# Structural Companion Catalogs
+
+Internal S05 reuse over the [canonical graph](content-model-graph.md), [typed reader](content-model-catalog.md), [reference resolution](content-model-resolution.md) and [composition](content-model-composition.md). See the root [README](../README.md).
+
+## Reader and common semantic result
+
+`prepareResolvedCompilationInput(input, options)` is the internal faithful counterpart exposed from [`semanticCatalog.ts`](../src/compiler/semanticCatalog.ts) and [`shapeResolver.ts`](../src/compiler/shapeResolver.ts).
+It accepts original source, catalog text or a catalog file, plus companion requests containing input and explicit global `NodeId` roots.
+Source loading requires the same explicit policy as S03; file/text inputs pass through the bounded S04 reader.
+An unused companion with no roots is never read or loaded.
+
+The result contains one `SemanticCatalog`, its `ResolvedGraph`, its `ComposedGraph`, and copy/deduplication evidence.
+Resolution and composition consume the same persisted declared graph after reuse.
+The union refreshes typed symbol-target links immutably before catalog validation; missing definitions supplied in either direction become ordinary resolved references.
+No catalog-specific derived representation feeds downstream consumers.
+
+Catalog format remains 2 and model/profile remain `xsd10-faithful-v1`.
+Derived views and merge metrics are recomputed, not persisted.
+Flattened legacy input returns the existing `regeneration-required` result with `requiredInput: "original-source"`; no structural semantics are inferred from TypeScript expressions.
+Unknown versions/models/profiles and corrupt catalogs retain existing reader diagnostics.
+
+Public `applyShapeCatalogs` and the CLI continue to use the legacy default adapter.
+The new internal entry does not activate faithful generation, projections, codecs or streaming transport.
+
+## Required closure and provenance
+
+`mergeStructuralCompanions(primary, companions, limits)` walks typed containment and reference slots from each requested global root.
+The visited set terminates self/mutual element-type recursion while retaining complete definitions.
+Groups, attribute groups, derivation bases, anonymous types and scalar/list/union references participate in the same closure.
+An unavailable imported definition may be supplied by the primary graph; the common resolver still verifies every use's original import visibility.
+Requested companion pools are indexed before traversal; required dependencies can be supplied by another pool regardless of request order.
+Unrelated operation/type nodes and their node-local unsupported constraints are not copied.
+
+Namespace, local name and symbol role define global identity.
+Loading interpretations never create extra global identities, and scoped declarations remain owned by their original containing components.
+No public symbol is renamed to make a collision disappear.
+
+Equal scoped definitions at normalized containment positions retain the primary declaration IDs and merge all corresponding origins.
+New definitions retain their original scoped IDs.
+Required schema-level retained syntax, annotations and import/include provenance accompany selected interpretations; source paths and digests remain available for diagnostics and assessment.
+The merged graph retains the primary loading-limit record; each companion was independently read/loaded under its own input limits, and reuse applies a separate semantic work budget.
+
+## Actual structural equality
+
+Equality compares normalized structural data from each global declaration and its owned local closure, using the shared [`semanticGraphRepresentation`](../src/compiler/catalogProvenance.ts).
+The full normalized structures must match; a matching fingerprint alone never establishes equality.
+Every reachable global dependency is independently copied or compared, including recursive dependencies.
+
+The comparison includes expanded namespace/role identity, ordered particles and compositors, exact occurrences, typed references, derivation kind/base/local content, scalar variety/facets, attribute use/value constraints, wildcard namespace/processing and retained unassessed syntax.
+It excludes retrieval locations, source digests, documentation and optional stored symbol-target hints.
+Scope positions normalize documentation-induced source-path shifts; lexical value contexts remain intact.
+
+This is conservative declared-structure equality, not a scalar value-equivalence or particle-language proof.
+Different lexical constraints or namespace contexts can require source reconciliation even when later assessment might prove them equivalent.
+It does not flatten inline content and group references into a claimed equivalence.
+The existing format-2 fingerprint algorithm remains unchanged; companion comparison separately ignores stored target-hint availability.
+
+Meaningful collisions throw `SemanticError` with category `invalid-schema`, the global component, the companion source and the existing source in `related`.
+The message asks for reconciliation of original declarations.
+Required missing references, forbidden cycles and import visibility failures flow through the common resolver.
+Unsupported retained constraints remain visible for #179; successful reuse does not certify their legality or capability.
+
+## Resource and support evidence
+
+Closure indexing/traversal, structural normalization and provenance copying consume bounded work.
+Normalization input and copied strings are counted before serialization; copied graph size is checked while adding definitions.
+Dynamic object keys, including namespace prefixes, count as copied strings.
+Defaults remain 100,000 nodes and 1,000,000 steps, with positive safe-integer overrides.
+Exhaustion returns `resource-limit` without modifying any input or returning a partial result.
+Input gathering bounds aggregate retained nodes and structural data before retaining each additional read, including redundant definitions.
+Gathering, merge, resolution and composition each apply that configured budget independently.
+S03's conservative cyclic-depth loading behavior remains unchanged.
+
+[Integration tests](../test/integration/structural-companions.test.ts) cover reader/source/file dispatch, recursive required closures, differing bounds, namespace/role collisions, chameleon and anonymous owners, source-path deduplication, missing references/cycles, structural collisions, legacy regeneration and catalog round trips.
+The [public characterization fixture](../test/conformance/fixtures/xsd/composition/derivation-boundaries.wsdl) is qualified for schema/payload behavior by both pinned reference engines.
+Its executable [registry row](../test/conformance/registry.ts) records legacy group omission, appended restriction content, ineffective prohibitions and named recursive references.
+[Supported patterns](supported-patterns.md) distinguishes this public characterization from internal faithful evidence.
+
+```bash
+npx tsc -p test/unit/tsconfig.json
+npx tsc -p test/integration/tsconfig.json
+npx tsc -p test/conformance/tsconfig.json
+npx vitest run test/integration/structural-companions.test.ts
+npm run test:conformance
+npm run test:reference:full
+npm run ci
+```
+
+#178 owns occurrence summaries/emptiness, #179 owns complete legality and reachable capability assessment, and #184 owns payload scalar enforcement.
+The documented oracle disagreements and S02 platform/security qualifications still apply.

package/docs/content-model-composition.md

@@ -0,0 +1,103 @@
+# Canonical Derivation Composition
+
+Internal S05 derivation views over immutable declarations. See the root [README](../README.md).
+
+## Input, result and assessment gate
+
+[`composeCanonicalGraph`](../src/compiler/composeCanonicalGraph.ts) consumes the reviewed [resolved-reference contract](content-model-resolution.md).
+It returns `ComposedGraph {resolved, types, metrics}` without changing the [canonical graph](content-model-graph.md).
+Each `ComposedType` retains its declaration ID, original derivation edge, effective content contributions, attributes, wildcard, scalar layers and explicit legality obligations.
+
+All results carry `assessment: "requires-schema-assessment"`.
+This boundary computes composition; it never certifies complete XSD legality, capability support or payload validity.
+No emitter accepts these internal views; #179 must discharge obligations before downstream planning under [ADR-003 D04](decisions/003-content-model-contracts.md#xsd-10-profile-and-enforcement-s02-d04).
+
+Content contributions reference declared particle IDs, preserving order and local bounds rather than flattening children.
+Builtin `anyType` remains an explicit opaque contribution with its original builtin reference.
+Attribute/wildcard source IDs and scalar owner layers trace every contribution to the declared graph.
+
+## Distinct derivation operations
+
+`extendContent(base, local)` concatenates the base root contributions followed by the local root particle.
+`restrictContent(local)` returns only the local root, or empty content when no particle is declared.
+Neither operation expands group definitions, calculates occurrences or mutates base and sibling types.
+
+```text
+Base:       optional a, optional b
+Extension:  Base roots, local extra
+Restriction: local optional a
+Empty restriction: no child particles
+```
+
+Complex-content derivation requires a complex base; simple-content extension requires a scalar-bearing base.
+Simple-content restriction retains facets and optional inline scalar types as ordered owner layers.
+Its mixed-base check uses the composed base, including effective mixed content inherited through an empty `anyType` extension.
+Named scalar restriction/list/union definitions and lexical contexts remain original graph data for #179/#184.
+
+Extension with no local content inherits the base's effective mixed content.
+An empty extension of `anyType` preserves opaque child content and its `##any` lax attribute wildcard.
+Restriction of `anyType` replaces child content and permits declared attributes through that base wildcard, while an omitted derived wildcard is removed.
+
+## Attribute-use composition
+
+Attribute groups are traversed separately from child model groups.
+Omitted restriction uses inherit base required/optional uses and their constraints.
+A declared prohibition removes an explicit optional use; weakening or prohibiting a required base attribute fails with `invalid-schema`.
+This applies to a direct type restriction; a prohibited use inside an attribute group contributes no attribute use and leaves inherited uses intact.
+
+Prohibitions remain traceable tombstones in the view rather than becoming wildcard QName exclusions.
+A matching retained wildcard can still admit that QName; prohibition removes an explicit use only.
+Extension prohibition contributes no new use and never removes a base use; conflicting inherited cases retain a legality obligation.
+
+Local redeclarations retain their actual declared types and default/fixed values.
+No missing local type is inferred from the base, and scalar values are never compared through Number or plain lexical equality.
+New restricted attributes require a matching base wildcard; type narrowing and applicable fixed-value equivalence retain both reference/value contexts for their enforcement owners.
+
+## Wildcard composition
+
+Each wildcard namespace is interpreted using its original effective namespace.
+`##other` excludes that namespace and the absent namespace; imported groups can therefore have different constraints despite identical lexical spelling.
+Finite sets and complements support exact union, intersection and subset checks without replacing lexical declarations.
+
+Group wildcards intersect namespace sets and preserve the first group wildcard's processing mode.
+Extension unions base and local namespace sets using the local processing mode, or inherits the base wildcard when no local wildcard exists.
+Restriction removes an omitted wildcard; an explicit wildcard must be a namespace subset with equal or stronger processing (`skip < lax < strict`).
+
+An intersection or union need not be expressible as one legal XSD 1.0 wildcard.
+The view retains the mathematical result and source operands; `wildcard-expressibility` remains an explicit #179 gate.
+Impossible restriction subsets and weakened processing fail here rather than being silently accepted.
+
+## Independent disagreements and remaining obligations
+
+Pinned xmlschema 4.2.0 and lxml 6.1.0/libxml2 2.14.6 disagree on duplicate extension uses and some extension prohibitions.
+They also disagree on fixed-value restrictions, group-plus-local wildcard processing and imported `##other` combinations.
+These cases are not added to verified support from either engine alone.
+
+Conflicting group/local processing returns `assessment-required` alternatives and original wildcard sources, with no invented selected mode.
+Each nested attribute group preserves its own processing obligation through callers.
+Fixed-value obligations retain both lexical values and type context, including value-equivalent integer spellings such as `1` and `+01`.
+Particle language inclusion, extension/mixed legality, attribute-type derivation, wildcard expressibility and scalar derivation remain explicit #179 obligations; #184 owns payload scalar enforcement.
+
+This division follows the existing S06 legality ownership rather than narrowing the approved profile.
+The [decision register](content-model-decisions.md) assigns these concrete evidence qualifications to #179; they block affected assessed plans.
+The S01/#181 disagreement and S02 transport/security qualifications remain unchanged.
+
+## Resources and evidence
+
+Composition defaults to 100,000 graph nodes and 1,000,000 work steps with positive safe-integer overrides.
+Iterative derivation order and bounded attribute-group expansion terminate independently of legal element/type recursion.
+Inherited content, attribute, wildcard and obligation copying consumes work; exhaustion returns `resource-limit` without a partial view.
+Provenance source-array copying is counted before allocation, including repeated references and derived merges.
+
+[Unit tests](../test/unit/composed-graph.test.ts) exercise contrasting extension/restriction, empty content, immutable siblings, attributes, wildcard operations, scalar/list/union contexts, opaque bases, catalog round trips and exact configured budgets.
+[Independent fixtures](../test/conformance/fixtures/xsd/composition/derivations.xsd) and [Node qualification](../test/conformance/reference/composition-contract.test.ts) assert current schema observations, scoped ordered payload contracts and separately recorded historical disagreements under [NT-CONT-01](reference-validation.md).
+
+```bash
+npx vitest run test/unit/composed-graph.test.ts test/unit/resolved-graph.test.ts
+npx tsc -p test/unit/tsconfig.json
+npm run test:reference:full
+npm run ci
+```
+
+These are internal faithful results; legacy default generation remains active.
+No occurrence summaries, complete legality checker, scalar payload engine, projection, codec or emitter rewrite belongs to S05.

package/docs/content-model-decisions.md

@@ -0,0 +1,79 @@
+# Content Model Decision Register
+
+Stable S02 decision IDs, evidence and downstream ownership. See the root [README](../README.md).
+
+## Ownership and dispositions
+
+The lead S02 implementation agent owns decision drafting/integration; independent review agents review semantic and integration domains. Maintainer approval is represented by the reviewed normal PR merge. Implementation ownership below means the named issue's assignee when taken up, not volunteering a contributor. The [ADR](decisions/003-content-model-contracts.md) owns the selected contracts.
+
+`Resolved` means a selected contract with evidence sufficient for its decision boundary; it does not claim later production code is implemented. `Open/blocking` identifies a decision that must be settled before its listed consumer. The initial draft passed independent semantic and integration review at `2f88ec81f77f4fc5a06b78f2d507ae8e20fe7a7c`; executed SOAP and gateway evidence now reconcile the selected contracts. Final delivery remains subject to the independent joint gate and required checks.
+
+## Register
+
+| ID / disposition | Selected contract and artifact | Supporting evidence | Decision owner / implementation owner | Consumers / resolution gate |
+|---|---|---|---|---|
+| S02-D01 Resolved | Ordered input, immutable graph, contextual URI identity; ADR input section | S01 order/count fixtures; XSD structures/namespaces | S02 lead / #171-#180 | S03-S07; independent reviewed draft and final joint gate |
+| S02-D02 Resolved | XML-value versus graph; reversible/normalized/lossy projections; ADR value section | S01 `sequence-order`, `empty-alternative`; epic CM-04/05/08 | S02 lead / #182/#183/#187 | S08/S10/S13; reviewed draft and final joint gate |
+| S02-D03 Resolved | Non-mutating idempotent normalization and three laws; ADR equivalence examples | S01 invisible groups; XSD datatype normalization | S02 lead / #182/#184/#188/#189 | S08/S10/#198; reviewed draft and final joint gate |
+| S02-D04 Resolved | XSD 1.0 profile and scalar/particle matrix; ADR profile section | S01 independent manifest; W3C XSD 1.0 | S02 lead / #179/#180/#184 | #187-#189/#198-#200; independent fixture gates |
+| S02-D05 Resolved | Separate client/HTTP projections; portable formats and fingerprint; ADR bundle section | Flattened-catalog information loss; epic CM-11/17 | S02 lead / #183/#185/#186 | #195/#196/#201; reviewed draft and final joint gate |
+| S02-D06 Resolved | OAS 3.1.1; separate draft-07 lowerings, validated fallback and shared checks; ADR dialect section | Independently reviewed #170 corpus and gateway evidence | S02 lead / #197/#198/#199/#200 | First consumers implement selected lowerings and independent validation |
+| S02-D06-OpenAPI Resolved | OAS 3.1.1 documentation, separate lowerings; ADR dialect section | Gateway evidence: current emitter is OAS 3.1.0; primary OAS 3.1.1 | S02 lead / #197 | #198/#199/#200; selected dialect/completeness must be emitted |
+| S02-D06-runtime Resolved | Strict non-mutating route-local draft-07 Ajv; gateway runtime section | Gateway 19-case corpus: mutation control, recursion, facets, keyword rejection | S02 lead / #198/#199 | #199/#200; missing supplemental plans fail closed |
+| S02-D06-serializer Resolved | Separate draft-07 serializer plan, independent validation; gateway serializer section | Gateway byte preservation and facet counterexamples | S02 lead / #197/#200 | #200; serializer cannot certify response validity |
+| S02-D06-fallback Resolved | Explicit validated JSON fallback; gateway complexity section | Imported current emitter at 149/150 refs; invalid response rejected by proposed boundary | S02 lead / #200 | #198/#200; retain validation schema when serializer schema is omitted |
+| S02-D06-supplemental Resolved | Inject one #180/#184 owner at validation boundaries; ADR scalar/dialect sections | Gateway exact int64/fractionDigits callback; annotation-only failure | S02 lead / #180/#184/#198 | #199/#200; no complete plan without shared checks |
+| S02-D06-closure Resolved | Graph-derived complete closure; no generic allOf merge; gateway composition section | Original closed composition rejects value accepted after current flattening | S02 lead / #197 | #198/#199/#200; each lowering must prove equivalence or diagnose |
+| S02-D07 Resolved | Buffered raw body/event and retained dedicated stream; minimum matrix and verification-before-yield; ADR transport section | Executed #169 HTTP/TLS/signing and raw/fault/cancel seams | S02 lead / #190/#192/#193 | #190/#192/#193 gate all unqualified capabilities before dispatch |
+| S02-D07-stream-qualification Open/consumer-blocking | Reject unqualified stream auth/TLS/version combinations; ADR transport and SOAP matrix | Executed current omissions; no qualified stream security claim | S02 lead / #192/#194 | #192/#194 resolve qualification; blocks affected #196/#200 dispatch, not S03's fixed graph/raw/capability contracts |
+| S02-D07-incoming-verification Open/consumer-blocking | Verify before decoding/yield or reject; ADR security/completion sections | Outgoing signatures verified; incoming/combined security unverified | S02 lead / #190/#192/#193/#194 | Named owners resolve incoming qualification; blocks authenticated yielding, not S03's proven raw access and fixed ordering contract |
+| S02-D08 Resolved | Consumption-driven success certifies declared response scope; ADR completion section | ADR-002 truncation policy; epic CM-13 | S02 lead / #185/#193/#194 | #196/#200/#202; reviewed draft and final joint gate |
+| S02-D09 Resolved | Numeric provisional budgets and errors; ADR budget table | Epic CM-16 boundedness requirement | S02 lead / #171/#172/#179/#180/#184/#193 | All first consumers; #208 refines measured limits |
+| S02-D10 Resolved | Legacy support, source regeneration, mixed rejection; 1.x default preserved; ADR compatibility section | S01 lost structure; current release v1.1.4 | S02 lead / #174/#185/#186/#195/#196/#201 | #204 qualification/#205 retirement; 2.0.0 release/default gate |
+| S02-D11 Resolved | Reject bounds-only, flattening, parse DTOs, one dialect and security bypass; ADR alternatives section | S01 counterexamples; ADR-002 | S02 lead / all semantic and adapter owners | Architecture PRs; reviewed draft and final joint gate |
+| S06-AU-01 Selected | [Repeated attribute-use research](content-model-s06-au-01.md) | C1 and all-original-base source replacement; independent typed/default contrasts | #233 research / #179 schema; #184 payload | Complete local review/delivery; production integration in #179 |
+| S06-RE-01 Open/blocking | [Reordered derivation research](content-model-s06-re-01.md) | Formal witnesses; empty-choice and wildcard counterexamples | #234 research / #179 integration | Complete approved-domain procedure, reviewed predicates and proof |
+| S06-PW-01 Selected | [Group-to-wildcard research](content-model-s06-pw-01.md) | Explicit project R-240 selection; reference disagreement | #235 research / #179 integration | Complete local review/delivery; production integration in #179 |
+| S06-DT-01 Selected | [Calendar research](content-model-s06-dt-01.md) | Explicit candidate A repairs; BCE correction; rollover contrasts | #236 research / #179 schema; #184 payload | Complete local review/delivery; shared implementation in #179/#184 |
+
+## Findings traceability
+
+S04's [immutable graph](content-model-graph.md) and [format 2 catalog boundary](content-model-catalog.md) implement the early D01/D04/D09/D10 consumers without changing the approved decisions or activating faithful generation.
+The #151 final handoff records independently reviewed revisions, validation results and the unchanged downstream qualification gates.
+
+| Finding | Decision and disposition | Implementation owner / evidence |
+|---|---|---|
+| CM-01/02/03 | D01/D02/D04 implement exact particles/projections | #178/#179/#180/#182/#198; S01 manifest |
+| CM-04/05 | D02/D03/D07 implement ordered values, normalize invisible history | #171 [ordered input](content-model-loading.md); later #182/#188/#189/#190/#192; SOAP probe |
+| CM-06/07 | D01/D04 implement namespace identity, references and derivation | #171/#172 [loading evidence](content-model-loading.md); #173 [graph contract](content-model-graph.md); later #175/#176/#179/#184 |
+| CM-08 | D02/D04 retain absence/empty/nil/attributes | #182/#183/#184/#187/#189; committed SOAP/gateway probes |
+| CM-09/10 | D06 non-mutating validation and independent serialization | #197/#198/#199/#200; committed gateway probe |
+| CM-11/17 | D05/D10 version/fingerprint routing; explicit activation | #174/#185/#186/#195/#196/#201/#204 |
+| CM-12 | D07 tested binding/security adapters, reject unverified combinations | #190/#192; committed SOAP probe |
+| CM-13/14 | D08 completion scope, isolated decoding and bounded lifecycle | #185/#187/#193/#194/#200 |
+| CM-15 | Independent evidence; preserve known oracle disagreement | #181/#207; S01 manifest, not altered by S02 |
+| CM-16 | D09 measurable first-owner limits | #171/#172 [measured loading limits](content-model-loading.md#loading-budgets); later #179/#180/#184/#193/#208 |
+
+## Probe and acceptance checkpoints
+
+S05's [derivation evidence](content-model-composition.md) adds concrete #179 qualification inputs without changing the approved profile.
+Duplicate extension uses, fixed-value equivalence, group/local wildcard processing and imported wildcard expressibility require independent reconciliation before affected plans are assessed.
+S05 preserves these as typed obligations with original operands; this is not a new scalar checker or a declaration of verified arbitrary derivation support.
+
+The [joint research handoff](content-model-s06-research-handoff.md) coordinates #232 and its four leaves against accepted #178 and the pinned unaccepted #231 draft.
+Its research-only manifest and separately invoked probes preserve primary expectations, conditional proposals and engine observations.
+The maintainer selected C1 with universal source-replacement matching, R-240 and candidate A's three calendar repairs after reviewing concrete alternatives.
+Local acceptance still requires complete independent review and exact delivery gates; RE01's complete negative proof remains open.
+Green research checks do not accept #232/#179/#153 or make S07/S08 Ready.
+The [TypeScript RE01 continuation](content-model-s06-re-01.md#witness-domain-and-comparison-decision) starts from unmerged #254 and separates component representation from recursive endpoint resolution with executable group-incidence, particle and existing-intermediate controls.
+Abstract construction plans plus a separately checked hypothetical graph overlay are recommended for investigation; comparison closure, context-sensitive legality and the full proof remain open, with accepted sibling contracts and existing production guards preserved.
+
+The [S02 handoff](content-model-s02-handoff.md) and #149 acceptance record pin reviewed draft/probe revisions and final delivery review/checks/merge. The SOAP source probe at `4d1d3972fbb0f8170232a3bd143f0fcf0adc842d` passed independent integration review; the gateway source probe at `d826ff506a80437bca1b747f40b772727643a506` passed independent semantic/gateway review.
+
+No foundational graph, projection, bundle/runtime, base transport or compatibility question remains open. The two open qualification entries block their affected transport/security consumers; their rejection and verification-order contracts are already resolved, so they do not change S03's input contract. Future shared scalar/particle, completion and compatibility implementations remain mandatory first-consumer gates, not already implemented features. S03 starts only after S02's joint gate closes.
+
+## Checked-product entry contract
+
+[P1-D01](decisions/003-content-model-contracts.md#checked-product-assessment-amendment-p1-d01) separates scoped, potentially inconclusive diagnostics from universal RE01 research acceptance. #367 owns the additive source API/report and assessment-only CLI; #368 measures that exact interface; #369 implements one later checked buffered client slice. #179/#153 retain full-profile ownership, and #234/#351/#362/#365 retain their unchanged research claims.
+
+The native-direct basis and dated-XSD correspondence are separate required dimensions. Unknown runtime capabilities remain unsupported or not-assessed, and whole-Gamma legality remains independent of operation reachability. Conditional admission #370 and public structured activation remain deferred.