@techspokes/typescript-wsdl-client 1.1.5 → 1.1.8

package/docs/checked-gateway.md

@@ -0,0 +1,210 @@
+# Checked gateway reference
+
+Generation offers legacy, the default, and opt-in checked components. Start with [Try Opt-in Checked Generation](checked-generation.md) for an installed trial and feedback instructions. This reference describes configuration, shipped direct-runtime compatibility and coverage boundaries.
+
+## Component service generation
+
+The additive `checked-components-v1` mode uses the same command family and native owners for qualified structured operations, imported schema snapshots, attributes, recursive records, simple content and ordered values. It preserves the shipped direct runtime and legacy defaults. Source, mapping, artifact and transport checks remain authoritative; unsupported schema or security features refuse rather than disappearing from a successful service claim. This is a qualified component fragment, not universal XSD, streaming or provider acceptance.
+
+For a supported local WSDL or HTTP(S) root URL with one service/port/binding candidate, omit `--checked-config`. The planner selects all operations of that binding and derives supported mappings through the existing native owners. Local sources default to their containing directory; remote sources authorize their same-origin declared dependency graph. Canonical containment, redirect permission checks and native qualification still apply.
+
+```bash
+npx wsdl-tsc pipeline --model checked-components-v1 --wsdl-source source.wsdl --client-dir .generated/service/client --openapi-file .generated/service/openapi.json --gateway-dir .generated/service/gateway --gateway-version-prefix v1 --gateway-service-name service --init-app --app-dir .generated/service --test-dir .generated/service/test --checked-report .generated/planning.json --checked-draft resolution.json
+```
+
+Partial configuration may supply `service`, `port`, `selectors` or permissions. Only missing unambiguous facts are inferred. Multiple candidates require a choice, including unsupported bindings; conflicting choices refuse. Explicit `selectors` still request a subset, while shared whole-source prerequisites remain mandatory. Reports retain the complete discovered inventory and mark other operations unselected and unassessed.
+
+Each operation retains its own client and capsule; the service index and gateway compose them without merging service/binding identities. `basePath` can separate services on a shared host. If omitted, it defaults to the supplied version/service route prefix. Paths append the exact, URI-encoded operation name.
+
+### Application groups and configured names
+
+Add `{"applicationGroups":{}}` to the existing `--checked-config` file, or set `checkedComponents: {applicationGroups: {}}` through the package-root API. This opts the generated contract into [source-derived groups](concepts.md#choice-groups-and-named-alternatives); leaving the option absent preserves existing component output and the frozen direct/legacy contracts.
+
+For a reconstructible source choice between `(A:int,B:string)` and `(C:boolean,D:string)`, a repeated group accepts `{"$choice":[{"A":7,"B":"card"},{"C":true,"D":"bank"}]}`. A singleton takes one alternative object; optional groups can be omitted. Repeated sequences use arrays under `$sequence`, and nested, independent and recursive definitions retain their own source rules.
+
+First generate defaults and copy the opaque `target` tokens from the client's `inventory.json`, under `applicationGroups.targets`. Each entry reports role, source owner/site, defaults and resolved names; the returned checked inventory exposes the same data. Then regenerate with this fragment inside the existing configuration:
+
+```json
+{
+  "applicationGroups": {
+    "names": [
+      {"target":"<choice-site token>","propertyName":"$payment","typeName":"PaymentMethod"},
+      {"target":"<first alternative token>","typeName":"CardPayment"},
+      {"target":"<second alternative token>","typeName":"BankPayment"}
+    ]
+  }
+}
+```
+
+The configured contract accepts only `$payment`; `$choice`, simultaneous spellings and payload-supplied configuration fail. Renaming the union does not rename alternatives. Defaults/configuration resolve once per authenticated definition; TypeScript, named OpenAPI components, HTTP validation and native forward/inverse mapping share that description across requests, success responses and declared faults.
+
+Targets survive physical relocation, unrelated global declaration reorder and alias changes. Relevant particle edits require generating defaults again and copying new tokens; stale or unknown targets, invalid names, duplicate targets and scoped collisions refuse before artifacts are written. Targets and inventory confer no source or runtime authority; generated capsules reconstruct the presentation from authorized source and reject incompatible contracts.
+
+The inventory's `applicationGroups.records` classifies each record as grouped, compact or retained-ordered with its reason. Empty-capable bodies, zero-width history and ambiguous partitions retain typed ordered values and ADR-003 normalization; `(N{1,2})*` cannot claim recoverable group boundaries for three `N` children. Optional repeated nonempty groups accept `[]` and normalize to omission without input mutation.
+
+Mixed/open/keyed records keep their existing owner, and same-record overlapping alphabets retain the native refusal; this slice does not add a general ambiguity matcher or a combined mixed/group grammar.
+
+### Nil values
+
+Checked component generation represents a present nil element as `{"$nil":true}`, with its existing source-mapped attribute properties. Required attributes remain required: a nillable element with required string `id` uses `{"$nil":true,"id":"7"}`. Optional attributes retain their scalar encodings, including empty strings and qualified attribute identities derived from the source.
+
+Omit an optional element to express absence. Empty non-nil content retains its ordinary representation; nil items occupy their own array positions, while a nil wrapper contains no items. Plain `null`, false/string nil markers, unknown metadata and all content fields on nil objects are rejected without coercion or field removal.
+
+The native matcher checks nillability, no character/element content on nil, declared/required attributes and scalar/fixed constraints. Optional attribute defaults/fixed values are assessed explicitly even on nil; element defaults apply only to empty non-nil content, and an element fixed value prohibits nil. Generated TypeScript and closed HTTP schemas describe the same nil alternatives; native checks retain XML-only duties.
+
+The [nil fixture](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/conformance/fixtures/assessment/nil.wsdl), [codec controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/direct-projection-nil.test.ts) and [installed gateway qualification](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/helpers/checkedGatewayInstalledProcess.ts) cover independently expected requests, responses and fault details through serialized HTTP JSON and an owned SOAP 1.1 service. This extends the existing qualified component domain; contextual scalar families and assessed dynamic types retain their existing capability refusals and owners. Legacy and shipped `checkedDirectRuntimeV1` contracts are unchanged.
+
+### Mixed, namespaced and open values
+
+Qualified component mappings use the [selected keyed contract](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/mapping-contract.md#selected-keyed-mapping-contract) for newly supported mixed and open content. Mixed records always have ordered `$content`, including empty and text-only instances. Entries contain one text `$value` or one child name; recursive children follow their own source-selected mapping.
+
+```json
+{"id":"7","$content":[{"$value":"Hello "},{"b":"world"},{"$value":"!"}]}
+```
+
+Adjacent text coalesces and empty text disappears; significant spaces, nesting and element order survive. Ordinary fixed records and already accepted ordered descendants retain their existing shapes. A same-name namespace choice needs `$namespace`; source-fixed positions derive identity and reject redundant holders. Metadata around a scalar retains its complete existing encoding under `$value`.
+
+Unambiguous peer attributes stay peers. Attribute/child collisions use `$attributes` one-name entries, deriving fixed qualified identities from the source. Open or ambiguous identities use an unqualified scalar or a qualified `{"$namespace":"urn:attributes","$value":"lexical"}` holder. Duplicate expanded identities, duplicate channels and undeclared fields fail without mutation.
+
+Strict wildcards require declarations and validation; lax validates available declarations and otherwise preserves unassessed data; skip preserves unassessed data. Unassessed elements always have `$namespace` and `$content`, with lexical attributes in `$attributes`. Raw xsi:type/xsi:nil remain lexical there, including unfamiliar values; assessed nil still uses `$nil`. Known invalid values and missing required children never become opaque success. Payload hints and namespace URIs acquire no schemas.
+
+`$namespaces` records effective bindings at a source-selected retained-context boundary, then local deltas on known intermediates and open descendants. Default bindings, resets, rebinding and sibling isolation survive fresh encoding. `$namespace` identifies a node independently of the default binding. Protected scopes cannot be rebound to satisfy encoding; impossible default/identity combinations and missing attribute prefixes fail. Original prefix spelling, bytes and arbitrary extracted-subtree portability are outside the guarantee.
+
+Generated TypeScript, OpenAPI and runtime schemas describe the actual fields and useful structural constraints; wildcard schemas can be structural supersets narrowed by native owners. Serialized success and fault values preserve all accepted metadata. The [production fixture](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/conformance/fixtures/assessment/keyed.wsdl), [namespace conformance](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/conformance/keyed-values.test.ts), [native controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/direct-projection-keyed.test.ts) and installed gateway qualification cover fresh hand JSON and independent SOAP expectations. General group/naming, contextual scalar families, assessed dynamic types, wider source/protocol families and streaming remain separate work.
+
+### URL intake and endpoint intent
+
+Use the same command above with `--wsdl-source https://provider.example/service.wsdl`. Declared WSDL imports and XSD imports/includes are acquired recursively; users supply no resource records or selectors. Relative references resolve against the actual final referring URI. Query strings remain distinct, shared resources are pinned once, and authorized HTTP redirect aliases are saved without rewriting original bytes. Cycles retain discovery identity; unsupported native or SOAP bootstrap graphs refuse during preparation.
+
+For a declared second origin, the reusable project decision is `{"sourceOrigins":["https://schemas.example"]}` in `--checked-config`. During URL acquisition a nonempty list adds to the supplied root origin; explicit `sourceOrigins: []` denies all HTTP metadata. Outside-root local inputs still require explicit `fileRoots`. Neither document references nor redirects permit remote-to-file transitions. Namespace names are never guessed as download locations. Missing locations use the existing draft/recovery workflow, and HTTP 401/403 identify metadata access failure rather than invalid schema.
+
+Generation copies original bytes and writes digest/provenance inventory plus generated runtime source records. `sourceUri` preserves a remote logical root; optional resource `canonicalUri` preserves a retrieval alias. Physical files remain independently authorized by `fileRoots`; logical origins remain independently permitted by `sourceOrigins`. An explicit `sourceResources` set, including an empty set, is closed and never acquires missing metadata. Runtime calls read physical snapshots and never download metadata. Every new generation invocation reacquires remote inputs; saved reports are not a cache or grant of authority.
+
+The component client and gateway use the selected WSDL service/port address when an operation is invoked. A runtime `endpoint` overrides that address. An omitted `allowEndpoint` client callback or `allowedEndpoints` gateway list permits that selected/configured destination; an explicit callback or list restricts it, and `allowedEndpoints: []` denies every call. An override cannot widen an explicit restriction. Destinations cannot come from HTTP request payloads, and SOAP redirects remain disabled. TLS, source policy, binding/action, typed input, response/fault and artifact checks remain mandatory.
+
+Previously, ordinary setup authored `sourceResources`, selectors, `endpoint` and a duplicate `allowedEndpoints` entry. Now supported URL intake needs only WSDL/model/output options, plus one `sourceOrigins` decision for each additional origin; ordinary runtime configuration uses generated source records and the selected address. Optional overrides and restrictions remain explicit. Generation, startup and scaffold tests make no business SOAP calls.
+
+This component injection change uses `checked-component-runtime-v2`; regenerate clients, capsules, gateways and server scaffolds together when upgrading. The exported binding name remains `checkedComponentRuntimeV1` for existing imports, and existing explicit endpoint callbacks remain valid after regeneration. Consumer server/config/test files retain skip/force ownership rules; use existing force options deliberately to refresh those scaffolds. The v1.1.5 direct runtime protocol and legacy defaults are unchanged.
+
+### Planning and missing-schema recovery
+
+`--checked-report` writes versioned `checked-component-plan-v1` JSON on native success or refusal. Human refusals identify the native reason, stage, dimension, affected full operation identities and configuration pointer. Source legality, correspondence, mapping/artifact readiness and runtime remain separate dimensions. Unsupported or inconclusive qualification does not establish invalid vendor schemas. Loading interruptions retain discovered counts plus explicit incomplete inventory; independent operation refusals are collected before generation writes project artifacts.
+
+For an unresolved locationless import, `--checked-draft` writes the known selection/permission configuration with `namespaceLocations: [{"namespace":"the-imported-namespace","location":"REQUIRED_SCHEMA_LOCATION"}]`. Replace that one value with an authorized schema path, then rerun the same pipeline with `--checked-config resolution.json`. Empty values and the unresolved placeholder refuse before source reads. Paths in generation configuration resolve from the invocation working directory. The user supplies missing source information, not a replacement type graph.
+
+Report and draft files use exclusive creation by default. `--force-checked-files` explicitly permits replacing those requested files; it is independent of scaffold `--force-init` and test `--force-test`. A draft is written only when a missing-schema resolution is available. Planning does not create a misleading partial project on semantic refusal. Filesystem write failures after emission starts remain operational failures; output is not claimed to be atomic.
+
+The package-root API shares that preparation:
+
+```typescript
+import {planCheckedComponents, runGenerationPipeline} from '@techspokes/typescript-wsdl-client';
+
+const report = await planCheckedComponents('/authorized/source.wsdl');
+console.log(report.ready, report.blockers);
+await runGenerationPipeline({
+  model: 'checked-components-v1', wsdl: '/authorized/source.wsdl',
+  clientOutDir: '.generated/service/client', openapi: {outFile: '.generated/service/openapi.json'},
+  gateway: {outDir: '.generated/service/gateway', versionSlug: 'v1', serviceSlug: 'service'},
+  app: {appDir: '.generated/service'}, test: {testDir: '.generated/service/test'},
+});
+```
+
+`planCheckedComponents` accepts the same partial component choices as `runGenerationPipeline.checkedComponents`. `CheckedPlanningError.report` exposes refusals from generation. `formatCheckedComponentPlan` formats human diagnostics, and `writeCheckedPlanningFile(path, data, force)` writes explicit report/draft data with ownership protection. Reports use opaque resource labels, digests and XML declaration positions; they omit source bytes and transport error details. The editable resolution configuration necessarily retains supplied filesystem permissions.
+
+Saved reports and copied plans grant no authority. Every separate invocation reloads authorized sources and reruns native qualification, selection, mapping and compatibility checks. Planning never dispatches SOAP, and generation readiness leaves runtime restrictions, credentials and provider acceptance unassessed. The old `checked-assessment-v1` and direct-preview scope are unchanged.
+
+### Explicit component configuration
+
+For the installed Forecast example below, a component configuration is:
+
+```json
+{
+  "selectors": [{
+    "portType": {"namespace": "urn:checked:forecast", "local": "ForecastPortType"},
+    "binding": {"namespace": "urn:checked:forecast", "local": "ForecastBinding"},
+    "operation": "GetForecast"
+  }],
+  "service": {"namespace": "urn:checked:forecast", "local": "ForecastService"},
+  "port": "ForecastPort",
+  "fileRoots": ["/absolute/path/to/tooling/node_modules/@techspokes/typescript-wsdl-client/docs/examples"],
+  "sourceResources": [],
+  "sourceOrigins": [],
+  "basePath": "/api/v1/forecast"
+}
+```
+
+Save it as `component-generation.json`, then use the same explicit outputs:
+
+```bash
+npx wsdl-tsc pipeline --model checked-components-v1 --checked-config component-generation.json --wsdl-source node_modules/@techspokes/typescript-wsdl-client/docs/examples/checked-forecast.wsdl --client-dir .generated/forecast/client --openapi-file .generated/forecast/openapi.json --gateway-dir .generated/forecast/gateway --gateway-version-prefix v1 --gateway-service-name forecast --init-app --app-dir .generated/forecast --test-dir .generated/forecast/test
+```
+
+Local dependencies are discovered under authorized roots; callers need not author snapshot bookkeeping. With explicit `sourceResources`, each entry has an original logical `uri` and an independently authorized physical snapshot `file`; the supplied snapshot set remains closed. HTTP metadata origins must be listed in `sourceOrigins` even though bytes are read from files. Missing snapshots refuse without network fallback. Optional `namespaceLocations` entries have `namespace` and `location` for imports without `schemaLocation`; explicit locations in source take precedence. Generation paths resolve from the invocation directory. Original source bytes are copied without modification and their provenance is recorded in `client/source-resources.json`.
+
+Install, typecheck, test, build and start using the trial guide. Generated `client/source-resources.json` uses `checked-source-resources-v2`: it retains the resource inventory and source/capsule defaults relative to its client-directory owner. Ordinary startup needs no authored graph configuration. The optional runtime JSON file contains endpoint, destination restrictions, host, port and trust choices; paths resolve relative to that file. Programmatic hosts can call `buildServer()` or pass equivalent overrides.
+
+Complete explicit source configurations remain advanced inputs, including older hosts that use them. An explicit `localSource`, `sourceUri`, `namespaceLocations`, `recordSources` or `capsuleFiles` requires `localSource`, `fileRoots`, `sourceResources` and `sourceOrigins` together; incomplete combinations refuse. Omitted restrictions preserve generated decisions, while explicit empty origins, snapshots, libraries and endpoint lists retain denial semantics. Generated defaults resolve canonically within their owner and verify snapshot digests; native physical-source and artifact checks still run independently on invocation. Runtime metadata stays offline. Cross-volume source layouts remain outside this scaffold.
+
+The component transport applies optional endpoint restrictions and requires verified HTTPS when required by source policy. An optional CA file does not disable verification. Client certificates, timestamps, required WS-Addressing, supporting tokens and security headers remain unsupported and refuse. Scalar facets, ordered particle languages and strict wildcard membership remain native supplemental checks, so OpenAPI marks JSON shape completeness false. `admitted:false` remains the full-profile marker. Generated scaffold tests are separate from independently specified HTTP/SOAP wire and provider/business evidence.
+
+For [SOAP 1.1 response headers](https://www.w3.org/TR/2000/NOTE-SOAP-20000508/), qualified optional blocks for the default receiver may be ignored when `mustUnderstand` is absent or `0`. Unknown mandatory blocks and actor-directed processing refuse; malformed attributes and unqualified blocks fail protocol checks. This processing grants no header security semantics or outgoing header capability.
+
+The copied-source scaffold records authorized HTTP redirect aliases for offline reconstruction. Local symlink aliases still refuse before emission; native loading authorization alone does not establish a relocatable local tree. Directory names beginning with two dots are ordinary names, not parent segments.
+
+### Explicit schema metadata and companion records
+
+`standardLibraries: ["w3c-xsd10-schema-element-2004-v1"]` explicitly supplies the dated XSD 1.0 global `xs:schema` declaration. The declaring schema must still import its namespace. A reference to this element requires an actual schema element in the response; it supplies neither a default payload nor a companion service's record declarations. Runtime callers must independently permit the same library.
+
+For a qualified schema-metadata-plus-strict-wildcard response, `recordProjections` can explicitly select a separate source contract for the payload. Each entry supplies the outer operation's full `selector`, physical companion `source`, companion `recordSelector` and the existing `scope: "records-with-declared-wrapper-scope"`. Native mappings derive the payload path, wrapper exclusions and a unique repeated complex-record path. If several paths exist, supply `recordPath` explicitly; the planner identifies the missing choice. No source or companion is discovered automatically.
+
+The complete older form remains supported. Instead of the concise `scope`/optional `recordPath`, supply a closed `spec`:
+
+```json
+{
+  "version": "component-record-scope-v1",
+  "scope": "records-with-declared-wrapper-scope",
+  "payloadPath": [{"namespace": "urn:owned:wrapper", "local": "Envelope"}],
+  "recordPath": [
+    {"namespace": "urn:owned:wrapper", "local": "Records"},
+    {"namespace": "urn:owned:wrapper", "local": "Record"}
+  ],
+  "opaqueExclusions": [
+    {"path": [{"namespace": "http://www.w3.org/2001/XMLSchema", "local": "schema"}], "reason": "standard-schema-metadata"},
+    {"path": [{"namespace": "urn:owned:wrapper", "local": "Envelope"}], "reason": "wrapper-declaration-universe"}
+  ]
+}
+```
+
+The path is relative to the outer response element; `recordPath` is relative to the companion output element. Both contracts are qualified independently, including when their output QNames coincide. Configuration does not merge their declarations or contact the companion service. Native checks must establish the supported wrapper structure and unique repeated-record path. The response retains the complete companion payload, including nonrecord fields; schema metadata is validated and omitted from the HTTP value. The declared scope does not claim wildcard validity against the outer declaration universe.
+
+Scoped artifacts use a distinct version from ordinary component artifacts. Generated runtime configuration adds explicit `recordSources`, each containing the outer full `selector` and independently authorized physical `source`. Both sources and their imported bytes are freshly checked on execution; embedded artifact bytes confer no permission. These responses are buffered under caller XML limits. No incremental delivery or streaming capability is claimed.
+
+## Native facets, lists and primitive-string unions
+
+Checked component requests, responses and declared faults support named, inline and inherited string length/whitespace restrictions, native-supported XSD patterns on strings and numeric families, and exact bounds/digit constraints on int32 and string-encoded integer/decimal values. Native scalar formation and membership remain authoritative, including Unicode character counts, inherited pattern layers, enumeration and default/fixed assessment. JSON schemas describe the actual representation; they do not translate XSD regex or put numeric keywords on exact decimal strings.
+
+Ordinary lists remain ordered arrays of selected item values. Patterned int items such as `+007` retain item strings; list-level patterns can require a single whole-list lexical string. Repeated XML elements remain distinct from one list-valued scalar. A list in a scalar identity holder or attribute entry keeps its complete encoding under `$value`.
+
+The bounded union subset has only effective atomic members with XSD primitive string and no contextual/document-wide obligations. JSON carries one complete lexical string before member-specific whitespace normalization. The native owner chooses the first successful effective member on every fresh inverse, including nested XSD 1.0 flattening; callers supply no branch tag. Lists of these unions contain lexical item strings, except when an existing whole-list witness is required. Whitespace-containing application items cannot be trimmed into legal tokens.
+
+Invalid input refuses before SOAP dispatch; invalid upstream responses and declared faults return non-success without a value. Strict and lax known declarations retain their scalar constraints; skip data remains lexical even when a name resembles a declared constrained type. Existing nil, attribute, namespace, mixed/open and companion mappings retain their separate native duties.
+
+`test/conformance/fixtures/assessment/facets.wsdl` and the installed gateway harness exercise these families through independent hand JSON and namespace-aware SOAP. `test/unit/direct-projection-string-unions.test.ts` checks native member order, pre-member witnesses, normalization, ownership, cancellation and limits. Heterogeneous unions, unions containing lists, contextual names/identity, dynamic types and wider source/protocol/security/streaming families remain outside this slice; their broad owners stay open.
+
+## Existing direct-runtime clients
+
+Generation supports legacy and `checked-components-v1`. The unpublished intermediate `checked-direct-v1` pipeline and `checkedDirect` option have been removed. For its former Forecast examples, select `checked-components-v1`, omit the old configuration or change `selector` to `selectors: [selector]`, and regenerate the complete project.
+
+The shipped `checkedDirectRuntimeV1` binding remains available for clients issued by v1.1.5. Its protocol, flat string/int32/Boolean grammar, physical-source checks and explicit owned IPv4-loopback endpoint authorization remain unchanged. This compatibility binding does not provide another generation workflow. Frozen published-producer client/capsule fixtures exercise it against the installed candidate runtime.
+
+Generated `buildServer` accepts runtime cancellation, timeout and XML limits. Ordinary execution has no implicit profiling quota or deadline. Project artifacts must be within `appDir` and nonoverlapping; generator-owned files regenerate together, while consumer scaffolds retain their skip/force rules.
+
+## Validation and coverage evidence
+
+OpenAPI documentation uses 3.1.1 with separate draft-07 HTTP runtime plans. Route-local Ajv disables coercion, default insertion and property removal, and preserves unrelated host policy. The native runtime explicitly converts validated HTTP values through the issued mapping, performs actual SOAP execution and independently validates response/fault XML. HTTP response validation also runs independently of serializer selection; JSON serialization preserves the validated values.
+
+`client/inventory.json` and the API result's `checked` field list every discovered portType operation, selected service/port/binding, requested/generated operation and unselected operations. Generation records `executed:false`; it does not claim a SOAP call occurred. Refused selection diagnostics name the requested operation and zero generated/executed operations. Unselected operations remain unassessed.
+
+Generated tests check scaffolding and invalid HTTP refusal without authorizing upstream transactions. The repository's `checked-gateway-installed.test.ts` separately packs and installs the candidate outside the checkout, invokes installed CLI/API, typechecks/tests/builds the projects and starts a separate process with checkout filesystem access denied. Independent XML and JSON expectations check normal exchanges, SOAPAction, namespaces, order, optional/repeated values, declared faults and invalid input/upstream/artifact/permission cases.
+
+Synthetic success establishes this delivery only. Positive representative real-service qualification and measured operation/family expansion remain under [#397](https://github.com/TechSpokes/typescript-wsdl-client/issues/397); production endpoint/security qualification remains under #190/#191. The broader [#401](https://github.com/TechSpokes/typescript-wsdl-client/issues/401) outcome and full-profile owners remain open.

package/docs/checked-generation.md

@@ -0,0 +1,161 @@
+# Try opt-in checked generation
+
+Version 1.1.8 offers an opt-in WSDL-to-checked-gateway workflow for early testing and feedback. Choose `pipeline --model checked-components-v1` to generate a typed SOAP client, OpenAPI, Fastify gateway, runnable app and scaffold tests for supported document/literal SOAP 1.1 contracts. Omitting `--model` keeps the existing legacy behavior.
+
+This is a bounded preview, not general WSDL/XSD or production-provider qualification. It adds source-backed request, response, fault and artifact checks for the supported fragment. Generation exposes legacy and components only; the shipped v1.1.5 direct runtime remains a compatibility binding for existing clients. See the [checked gateway reference](checked-gateway.md).
+
+## Install and try the bundled contract
+
+Use Node.js 24 or newer. Run these commands in a new trial directory:
+
+```powershell
+npm init -y
+npm install --save-dev @techspokes/typescript-wsdl-client@1.1.8
+npm install soap
+npx wsdl-tsc pipeline --model checked-components-v1 --wsdl-source node_modules/@techspokes/typescript-wsdl-client/docs/examples/checked-forecast.wsdl --client-dir .generated/forecast/client --openapi-file .generated/forecast/openapi.json --gateway-dir .generated/forecast/gateway --gateway-version-prefix v1 --gateway-service-name forecast --init-app --app-dir .generated/forecast --test-dir .generated/forecast/test --checked-report .generated/forecast-plan.json
+```
+
+The bundled [Forecast contract](examples/checked-forecast.wsdl) is synthetic and has no running SOAP backend. Generation selects its one unambiguous service/port/binding and `GetForecast` operation without a configuration file. Its placeholder SOAP address must be replaced with your owned test backend before invoking the operation.
+
+The generated project includes `client/inventory.json`, copied WSDL/XSD sources and provenance, operation clients/contracts, OpenAPI, gateway routes, server configuration and scaffold tests. The planning report lists readiness and blockers; the inventory records discovered, selected and generated operations. Generation does not mean an operation was executed.
+
+## Check and start the generated project
+
+Run from the generated app directory below. Its package supplies test/typecheck dependencies and scripts; scaffold tests check health, selected OpenAPI and invalid-input refusal without upstream SOAP dispatch. See [consumer testing guidance](testing.md#for-consumer-projects) for emitted configuration, customization protection and independent verification boundaries.
+
+```powershell
+Set-Location .generated/forecast
+npm install
+npm run typecheck
+npm test
+npm run build
+npm start
+```
+
+Generation, installation, startup and scaffold tests do not execute business SOAP operations. Startup loads generated bookkeeping, verifies its owned snapshot digests and checks gateway/OpenAPI identity. Native source qualification and source/contract compatibility run independently when an operation is invoked; a healthy server alone does not prove SOAP readiness. In a second terminal, inspect the running gateway:
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:3000/health
+Invoke-RestMethod http://127.0.0.1:3000/openapi.json
+```
+
+Stop the foreground server with Ctrl+C when finished. The npm and generation commands also work in POSIX shells. No runtime configuration file is required for ordinary startup.
+
+## Try your WSDL file or URL
+
+Run from the trial directory, using a fresh output directory for a different contract. Replace the source with your local WSDL or an HTTP(S) metadata URL you are permitted to access:
+
+```powershell
+npx wsdl-tsc pipeline --model checked-components-v1 --wsdl-source https://provider.example/service.wsdl --client-dir .generated/service/client --openapi-file .generated/service/openapi.json --gateway-dir .generated/service/gateway --gateway-version-prefix v1 --gateway-service-name service --init-app --app-dir .generated/service --test-dir .generated/service/test --checked-report .generated/service-plan.json --checked-draft service-resolution.json
+```
+
+The loader follows declared WSDL imports and XSD imports/includes recursively, including authorized redirects. Same-origin dependencies require no authored resource map or selectors. For local input, the containing directory is the default permitted root; authorize outside-root files explicitly through `fileRoots` in `--checked-config`.
+
+For a declared dependency on another origin, save a reusable project configuration such as `intake.json` and add `--checked-config intake.json` to the command:
+
+```json
+{
+  "sourceOrigins": ["https://schemas.example"]
+}
+```
+
+During URL acquisition, nonempty `sourceOrigins` adds those exact origins to the root origin. Explicit `sourceOrigins: []` denies all HTTP metadata. An explicit `sourceResources` set is closed, including an empty set, so omit it for ordinary automatic acquisition. HTTP 401/403 are metadata-access failures; the preview does not supply a credential broker.
+
+Generated configuration points runtime calls at copied physical snapshots. Keep the generated source/provenance/configuration files together when moving the project; runtime does not download metadata. Rerunning generation from a URL reacquires its sources.
+
+## Resolve a missing schema or ambiguous selection
+
+Read the planning report before editing anything. Unsupported source, mapping, binding or security cases refuse with a stage and reason; a refusal does not necessarily mean the vendor schema is invalid.
+
+Checked planning refusals show the construct or source location, the reason and the next action, then exit nonzero without generating artifacts or invoking SOAP. Save the unchanged structured report with `--checked-report`; set the `DEBUG` environment variable to `wsdl-tsc` when you need the raw error, stack and report details.
+
+For a locationless import, `--checked-draft` can write `service-resolution.json` containing a `REQUIRED_SCHEMA_LOCATION` placeholder. Replace that value with the actual permitted schema location, then rerun with `--checked-config service-resolution.json`. This supplies missing source information; it does not waive native checks or reconstruct a type graph by hand.
+
+Multiple service/port/binding candidates require an explicit choice. Partial configuration and operation subsets are supported; see [selection and recovery details](checked-gateway.md#planning-and-missing-schema-recovery). Reports and drafts are preserved by default; use `--force-checked-files` deliberately to replace them on a later run.
+
+The Weather quick-start fixture has multiple ports even though it has one service. Set `service`, `port` and `selectors` in a JSON file supplied through `--checked-config`; the diagnostic lists actual service/port choices and the report lists operation candidates. Legacy mode is a separate generation path with its own support limits, not an automatic fallback after a checked refusal.
+
+## Configure and invoke an owned SOAP backend
+
+The component gateway normally uses the selected WSDL service/port address when a route is invoked. To use an owned test service, create `checked-gateway.local.json` with this complete concise override:
+
+```json
+{
+  "endpoint": "http://127.0.0.1:8081/forecast"
+}
+```
+
+An optional `allowedEndpoints` list narrows the permitted destinations; omitting it permits the selected/configured endpoint, and `[]` denies every call.
+
+Select the optional file and start in PowerShell:
+
+```powershell
+$env:CHECKED_GATEWAY_CONFIG = 'checked-gateway.local.json'
+npm start
+```
+
+In a POSIX shell, use `CHECKED_GATEWAY_CONFIG=checked-gateway.local.json npm start`. Optional `host`, `port` and `caFile` are separate caller choices. Generated `client/source-resources.json` owns source and capsule records; do not copy them into this file.
+
+Restart the gateway after changing runtime configuration. Only after an owned SOAP backend implements the bundled Forecast contract, invoke its JSON route:
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:3000/v1/forecast/GetForecast -Method Post -ContentType 'application/json' -Body '{"city":"Paris","days":2}'
+```
+
+This POST executes a real SOAP operation. Supply independently chosen expected values and fault cases for your own service; WSDL and generated scaffold tests cannot establish business correctness. Component responses retain their checked JSON value/fault shapes, while legacy envelopes, raw client fields and streaming behavior remain unchanged.
+
+TLS verification stays enabled. The optional `caFile` supplies a trusted CA; it does not disable verification. SOAP redirects remain disabled, and unsupported authentication or WS-Security requirements refuse. Check the [transport limits](checked-gateway.md#explicit-component-configuration) before trying a provider integration.
+
+## Programmatic planning and generation
+
+The package-root API uses the same loader and native preparation as the CLI:
+
+```typescript
+import {planCheckedComponents, runGenerationPipeline} from '@techspokes/typescript-wsdl-client';
+
+const source = './service.wsdl';
+const report = await planCheckedComponents(source);
+console.log(report.ready, report.blockers);
+await runGenerationPipeline({
+  model: 'checked-components-v1', wsdl: source,
+  clientOutDir: '.generated/service/client',
+  openapi: {outFile: '.generated/service/openapi.json'},
+  gateway: {outDir: '.generated/service/gateway', versionSlug: 'v1', serviceSlug: 'service'},
+  app: {appDir: '.generated/service'}, test: {testDir: '.generated/service/test'},
+});
+```
+
+Partial choices and permissions go in `checkedComponents` for generation or the second argument to `planCheckedComponents`. Planning never invokes SOAP. Generation performs fresh checks even when an earlier planning report was ready.
+
+The older `assessSchemaSource` API and `assess` command retain the narrow `checked-assessment-v1` direct-schema scope and exit codes. They do not assess component generation or provider readiness. Use the component planner and `--checked-report` for this workflow; saved reports are diagnostic data.
+
+## Supported scope and direction
+
+The qualified component fragment includes imported schemas, nested/repeated and inherited records, attributes, simple content, ordered values and supported scalar restrictions. [Keyed mixed/namespace/open values](checked-gateway.md#mixed-namespaced-and-open-values) additionally preserve source-permitted wildcard data with native strict/lax/skip checks. Escapia qualification retains 15 Main operations and two Content operations against owned services. Content uses explicit companion configuration with scoped validation and buffered delivery; it is not automatic companion discovery or checked streaming.
+
+General XSD, SOAP 1.2/RPC-encoded, broader authentication/security, arbitrary wildcard conversion and checked incremental streaming remain outside this preview. OpenAPI describes the JSON shape but does not express every native scalar/order/wildcard rule. Required declarations and strict wildcard failures cannot become successful unchecked replies.
+
+[#409](https://github.com/TechSpokes/typescript-wsdl-client/issues/409) supplies the bounded mixed/namespace/open mapping and its schema/serialization slice of [#410](https://github.com/TechSpokes/typescript-wsdl-client/issues/410). Representative unrelated contract qualification remains under [#397](https://github.com/TechSpokes/typescript-wsdl-client/issues/397); broader HTTP translation, source, scalar, group/naming, security and streaming work retains its existing owners. Legacy defaults and full-profile activation remain unchanged. See the [roadmap](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/ROADMAP.md) for direction and [development checkpoint](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/docs/content-model-development-checkpoint.md) for detailed evidence.
+
+## Send useful feedback
+
+Use [Issues](https://github.com/TechSpokes/typescript-wsdl-client/issues/new/choose) for reproducible defects and [Discussions](https://github.com/TechSpokes/typescript-wsdl-client/discussions) for questions or integration reports. Mention `checked-components-v1` in the title and include:
+
+- Package version, Node version and operating system.
+- The exact generation command, model and relevant configuration choices.
+- WSDL/dependency sources you have permission to share, or a minimal reproducer.
+- The affected service, port, binding and operation, plus the planning blocker or inventory entry.
+- Expected and actual generated types, JSON, SOAP values or refusal behavior.
+- Whether you tested generation, scaffold/startup checks, owned wire execution or provider business acceptance.
+
+Remove credentials and private data from configurations, source URLs, reports and payloads before posting. Include a known expected request/response or fault when reporting wire behavior. Report an unsupported capability as such rather than requesting that typed validation be disabled; this helps prioritize the smallest useful expansion without losing existing guarantees.
+
+## Upgrade and regenerate
+
+Regenerate checked clients, contracts, copied sources, gateways and server scaffolds together with the matching installed runtime. The generated source record now uses the explicit `checked-source-resources-v2` format; it is separate from the component runtime protocol. Complete older runtime configurations remain supported as advanced inputs. Supplying `localSource`, `sourceUri`, `namespaceLocations`, `recordSources` or `capsuleFiles` selects that advanced form and requires all four source fields: `localSource`, `fileRoots`, `sourceResources` and `sourceOrigins`.
+
+With generated defaults, omitted restrictions retain the generated choices; explicit `sourceOrigins: []`, `sourceResources: []`, `standardLibraries: []` and `allowedEndpoints: []` remain restrictive. Incomplete advanced configurations refuse instead of mixing incompatible sources with generated defaults. Runtime paths in the optional JSON file resolve relative to that file; programmatic paths remain caller-owned.
+
+Consumer-owned server/config/test files are preserved unless their existing `--force-init` or `--force-test` option is selected. Review customizations before deliberately refreshing older host scaffolds. Existing v1.1.5-issued direct clients continue using `checkedDirectRuntimeV1` unchanged; new generation uses components.
+
+Legacy users need no model change. Refresh existing consumer dependency lockfiles separately to pick up transitive security fixes.

package/docs/cli-reference.md

@@ -1,5 +1,7 @@
 # CLI Reference
 
+Generation offers legacy, the default, and opt-in `pipeline --model checked-components-v1`. Start with [Try Opt-in Checked Generation](checked-generation.md); the [checked gateway reference](checked-gateway.md) covers exact configuration and v1.1.5 runtime compatibility. Checked generation emits source-backed contracts rather than a legacy catalog and refuses unsupported compiler/streaming controls.
+
 The `wsdl-tsc` tool generates TypeScript SOAP clients, OpenAPI specifications, and Fastify gateways from WSDL files.
 
 Generation paths are explicit. Examples use the git-ignored `.generated/` directory for disposable consumer output, while this repository reserves `tmp/` for its own test and release automation.
@@ -22,6 +24,24 @@ TypeScript outputs automatically receive [generated preambles](generated-code.md
 
 ## pipeline
 
+The `--model` selector defaults to `legacy`. `checked-components-v1` derives unambiguous service/port/binding selections and supported mappings from local WSDL or HTTP(S) input. Optional `--checked-config` supplies actual choices or permissions. The catalog/compiler/streaming tables below describe legacy behavior unless stated otherwise.
+
+### Checked generation flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--model checked-components-v1` | Opt into qualified structured component generation |
+| `--checked-config` | JSON path for partial component choices and permissions |
+| `--checked-report` | JSON output path for a component planning report on readiness or refusal |
+| `--checked-draft` | JSON output path for an available component missing-schema recovery draft |
+| `--force-checked-files` | Deliberately replace requested component report/draft files |
+
+Checked planning refusals print a concise reason, construct/location and next action and exit nonzero. Their JSON reports remain available through `--checked-report`; set `DEBUG=wsdl-tsc` to include the raw error, stack and report details. Ambiguous selections use `service`, `port` and `selectors` in `--checked-config`, rather than separate service/port flags.
+
+Component URL intake follows declared same-origin dependencies automatically. Extra origins need a reusable `sourceOrigins` decision in the checked configuration. Generated snapshots supply offline runtime bookkeeping; optional host/endpoint/trust overrides belong to the runtime configuration. The [trial guide](checked-generation.md) shows complete commands and explains the unchanged direct-runtime compatibility binding.
+
+Checked modes require all three explicit outputs: `--client-dir`, `--openapi-file` and `--gateway-dir`, plus `--gateway-service-name` and `--gateway-version-prefix`. For a runnable checked app, supply `--init-app` and an explicit `--app-dir` containing those outputs; scaffold tests use `--test-dir` with app generation. The legacy one-output minimum below does not apply to checked generation.
+
 Run the complete generation pipeline in one pass: WSDL parsing, TypeScript client, OpenAPI spec, Fastify gateway, and optional app. This is the recommended command for most use cases.
 
 ### Usage
@@ -131,6 +151,8 @@ When `--init-app` is used and `--openapi-servers` is not provided, servers defau
 
 ### Test Suite Flags
 
+Legacy tests need consumer test/runtime dependencies and use their emitted Vitest config. Checked tests require app generation and use the checked app's scripts; see [consumer testing guidance](testing.md#for-consumer-projects) for complete setup/run examples and coverage limits. Existing scaffold files are preserved unless their force option is selected.
+
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--test-dir` | (none) | Generate Vitest test suite in this directory (requires client, gateway) |
@@ -639,7 +661,7 @@ cat ./debug/catalog.json | jq '.operations'
 
 ## assess
 
-Inspect source schema evidence without generating artifacts or dispatching SOAP. The [assurance contract](decisions/003-content-model-contracts.md#checked-product-assessment-amendment-p1-d01) defines the native scope and qualified correspondence route.
+Inspect source schema evidence without generating artifacts or dispatching SOAP. The [assurance contract](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/003-content-model-contracts.md#checked-product-assessment-amendment-p1-d01) defines the native scope and qualified correspondence route.
 
 ```bash
 npx wsdl-tsc assess --wsdl-source examples/minimal/weather.wsdl --report .generated/assessment.json