@blockml/xsd-target 0.1.0

package/blocks/org/blockml/bml/target/xsd/capability/ResolveOptions.bml

@@ -0,0 +1,44 @@
+<!--
+  XSD Capability — ResolveOptions
+  FQN: org.blockml.bml.target.xsd.capability.ResolveOptions
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>ResolveOptions</name>
+  <type>xsdcap:ResolveOptions</type>
+  <baseType>core:Capability</baseType>
+  <is>Merge opaque targetOptions into required XsdOptions</is>
+
+  <documentation>XSD15/XSD16: defaults includeNonExported=true, emitDomainSchemas=true. includeNonExported has no V1 emit effect.</documentation>
+
+  <references>
+    <see type="xsddocumentation:PublicApi" relation="SeeAlso" />
+    <see type="xsdconfig:DefaultXsdOptions" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <targetOptions type="type:Text">
+      <documentation>Opaque CompileRequest.targetOptions. (optional)</documentation>
+    </targetOptions>
+    <result type="xsdapi:XsdOptions">
+      <documentation>Fully resolved options. (required)</documentation>
+    </result>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/capability/VocabularyElements.bml

@@ -0,0 +1,42 @@
+<!--
+  XSD Capability — VocabularyElements
+  FQN: org.blockml.bml.target.xsd.capability.VocabularyElements
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>VocabularyElements</name>
+  <type>xsdcap:VocabularyElements</type>
+  <baseType>core:Capability</baseType>
+  <is>List sorted short names under an FQN prefix</is>
+
+  <documentation>Shared helper for types/service emit: filter registry.keys by prefix; take last segment after dot; sort.</documentation>
+
+  <properties>
+    <typeRegistry type="type:Text">
+      <documentation>TypeRegistry. (required)</documentation>
+    </typeRegistry>
+    <prefix type="type:Text">
+      <documentation>FQN prefix. (required)</documentation>
+    </prefix>
+    <result type="type:Text">
+      <documentation>Sorted short names. (required)</documentation>
+    </result>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/config/DefaultXsdOptions.bml

@@ -0,0 +1,33 @@
+<!--
+  XSD Config — DefaultXsdOptions
+  FQN: org.blockml.bml.target.xsd.config.DefaultXsdOptions
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>DefaultXsdOptions</name>
+  <type>xsdconfig:DefaultXsdOptions</type>
+  <baseType>xsd:XsdType</baseType>
+  <is>Defaults applied by ResolveOptions</is>
+
+  <properties>
+    <includeNonExported type="type:Boolean"><documentation>true</documentation></includeNonExported>
+    <emitDomainSchemas type="type:Boolean"><documentation>true</documentation></emitDomainSchemas>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/config/XsdConstants.bml

@@ -0,0 +1,42 @@
+<!--
+  XSD Config — XsdConstants
+  FQN: org.blockml.bml.target.xsd.config.XsdConstants
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>XsdConstants</name>
+  <type>xsdconfig:XsdConstants</type>
+  <baseType>xsd:XsdType</baseType>
+  <is>Well-known namespace URIs, FQN prefixes, and D1 particle lists</is>
+
+  <documentation>XSD4–XSD9 constants. D1 identity and container element name lists are normative for V1 bml.xsd emit.</documentation>
+  <properties>
+    <BML_DOCUMENT_NS type="type:Text"><documentation>http://blockml.org/bml</documentation></BML_DOCUMENT_NS>
+    <BML_TYPES_NS type="type:Text"><documentation>http://blockml.org/schema/types</documentation></BML_TYPES_NS>
+    <BML_SERVICE_NS type="type:Text"><documentation>http://blockml.org/schema/service</documentation></BML_SERVICE_NS>
+    <TYPE_FQN_PREFIX type="type:Text"><documentation>org.blockml.bml.type.</documentation></TYPE_FQN_PREFIX>
+    <SERVICE_FQN_PREFIX type="type:Text"><documentation>org.blockml.bml.service.</documentation></SERVICE_FQN_PREFIX>
+    <D1_IDENTITY_ELEMENTS type="type:Text"><documentation>Hardcoded identity particle names including both isNot and isnot.</documentation></D1_IDENTITY_ELEMENTS>
+    <D1_CONTAINER_ELEMENTS type="type:Text"><documentation>Hardcoded container particle names.</documentation></D1_CONTAINER_ELEMENTS>
+    <META_DEFINITION_FQNS type="type:Text"><documentation>Definition FQNs walked for extra element names.</documentation></META_DEFINITION_FQNS>
+    <REGISTRY_NAME type="type:Text"><documentation>xsd</documentation></REGISTRY_NAME>
+    <ACCEPTS type="type:Text"><documentation>library, corpus, auto</documentation></ACCEPTS>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/documentation/ArchitectureOverview.bml

@@ -0,0 +1,45 @@
+<!--
+  XSD Documentation — ArchitectureOverview
+  FQN: org.blockml.bml.target.xsd.documentation.ArchitectureOverview
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>ArchitectureOverview</name>
+  <type>xsddocumentation:ArchitectureOverview</type>
+  <baseType>core:Documentation</baseType>
+  <is>Modules and data flow</is>
+
+  <documentation>Public entry: XsdTarget.render → ResolveOptions then emit helpers.
+    Modules map 1:1 to capabilities:
+    options.ts → ResolveOptions; constants.ts → XsdConstants;
+    emit-block-xsd.ts → EmitBlockXsd / MemberPrefersElement / ExtraElementNames;
+    emit-types-xsd.ts / emit-service-xsd.ts → EmitTypesXsd / EmitServiceXsd / VocabularyElements;
+    emit-catalog-xml.ts → EmitCatalogXml / CatalogRelativePath;
+    xsd-target.ts → Render.
+
+    Accepts library|corpus|auto (XSD2). Always emits bml.xsd (XSD1/XSD3). Domain schemas
+    gated by emitDomainSchemas (XSD15). Catalog always in rootFiles (XSD14).</documentation>
+  <references>
+    <see type="xsddocumentation:V1Scope" relation="ReadNext"></see>
+    <see type="xsdcap:Render" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/documentation/CatalogAndOutputLayout.bml

@@ -0,0 +1,45 @@
+<!--
+  XSD Documentation — CatalogAndOutputLayout
+  FQN: org.blockml.bml.target.xsd.documentation.CatalogAndOutputLayout
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>CatalogAndOutputLayout</name>
+  <type>xsddocumentation:CatalogAndOutputLayout</type>
+  <baseType>core:Documentation</baseType>
+  <is>Output files and OASIS catalog (XSD14)</is>
+
+  <documentation>files[]: always bml.xsd; if emitDomainSchemas also types.xsd and service.xsd
+    (paths relative to session outputBasePath / CLI default schemas/).
+    rootFiles[]: always catalog.xml at project root (CLI writes separately).
+
+    XSD14: OASIS xmlns urn:oasis:names:tc:entity:xmlns:xml:catalog;
+    one uri per CatalogEntry (name=namespaceUri, uri=CatalogRelativePath).
+    CatalogRelativePath: normalize slashes, strip trailing, return ./outDir/file.
+
+    IDE catalog usage is host/docs 15; generation rules live here.</documentation>
+  <references>
+    <see type="xsddocumentation:Diagnostics" relation="ReadNext"></see>
+    <see type="xsdcap:EmitCatalogXml" relation="SeeAlso"></see>
+    <see type="cli:Library" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/documentation/DesignDecisions.bml

@@ -0,0 +1,49 @@
+<!--
+  XSD Documentation — DesignDecisions
+  FQN: org.blockml.bml.target.xsd.documentation.DesignDecisions
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>DesignDecisions</name>
+  <type>xsddocumentation:DesignDecisions</type>
+  <baseType>core:Documentation</baseType>
+  <is>Normative XSD decisions XSD1–XSD18</is>
+
+  <documentation>XSD1 Always emit bml.xsd.
+    XSD2 accepts library|corpus|auto; registry name xsd.
+    XSD3 Render uses session typeRegistry and outputBasePath.
+    XSD4–XSD7 bml.xsd shell: NS, block root, mixed, choice elements, no xs:any, lax anyAttribute.
+    XSD8 Hardcoded D1 identity + container name lists (including isNot and isnot).
+    XSD9 META_DEFINITION_FQNS walk for extras.
+    XSD10 MemberPrefersElement weak filter.
+    XSD11 Extras unique sorted minus D1 lists.
+    XSD12 types.xsd string vocabulary.
+    XSD13 service.xsd string vocabulary.
+    XSD14 Always catalog.xml in rootFiles; relative ./outDir/file paths.
+    XSD15 emitDomainSchemas default true.
+    XSD16 includeNonExported reserved unused in V1.
+    XSD17 No package-local emit diagnostics.
+    XSD18 Authoring XSD validation is CLI ScopeExclusion — not an XSD capability.</documentation>
+  <references>
+    <see type="xsddocumentation:PackageOwnership" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/documentation/Diagnostics.bml

@@ -0,0 +1,38 @@
+<!--
+  XSD Documentation — Diagnostics
+  FQN: org.blockml.bml.target.xsd.documentation.Diagnostics
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>Diagnostics</name>
+  <type>xsddocumentation:Diagnostics</type>
+  <baseType>core:Documentation</baseType>
+  <is>Emit path has no package-local diagnostics</is>
+
+  <documentation>V1 XSD target emits without package diagnostics codes. Failures surface as host/CLI
+    or empty/malformed output only if upstream session is broken.
+    Authoring validation diagnostics (--no-xsd) are CLI-owned, not modeled here.
+    Scope mismatch for accepts is compiler/CLI (BML_TARGET_SCOPE_MISMATCH).</documentation>
+  <references>
+    <see type="xsddocumentation:DesignDecisions" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/documentation/DomainVocabularyRules.bml

@@ -0,0 +1,41 @@
+<!--
+  XSD Documentation — DomainVocabularyRules
+  FQN: org.blockml.bml.target.xsd.documentation.DomainVocabularyRules
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>DomainVocabularyRules</name>
+  <type>xsddocumentation:DomainVocabularyRules</type>
+  <baseType>core:Documentation</baseType>
+  <is>types.xsd and service.xsd vocabularies (XSD12–XSD13)</is>
+
+  <documentation>XSD12: EmitTypesXsd — VocabularyElements under TYPE_FQN_PREFIX as xs:element type=xs:string
+    in BML_TYPES_NS (http://blockml.org/schema/types).
+    XSD13: EmitServiceXsd — same for SERVICE_FQN_PREFIX under BML_SERVICE_NS.
+    Short name = last FQN segment after dot; sorted.
+    Gated by emitDomainSchemas (XSD15). Not MachineBlocks domain schemas.</documentation>
+  <references>
+    <see type="xsddocumentation:CatalogAndOutputLayout" relation="ReadNext"></see>
+    <see type="xsdcap:EmitTypesXsd" relation="SeeAlso"></see>
+    <see type="xsdcap:EmitServiceXsd" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/documentation/Introduction.bml

@@ -0,0 +1,50 @@
+<!--
+  XSD Documentation — Introduction
+  FQN: org.blockml.bml.target.xsd.documentation.Introduction
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>Introduction</name>
+  <type>xsddocumentation:Introduction</type>
+  <baseType>core:Documentation</baseType>
+  <is>Purpose and scope of the XSD render target</is>
+
+  <documentation>The @blockml/xsd-target package implements RenderTarget registry name xsd.
+    It emits universal bml.xsd from D1 defaults plus meta Definition extras, optional
+    types.xsd and service.xsd vocabularies, and a root catalog.xml.
+
+    This library (org.blockml.bml.target.xsd.*) is the SSOT. TypeScript in
+    packages/xsd-target/src/ implements it. Tests in packages/xsd-target/test/
+    encode behavioral contracts (XSD1–XSD18).
+
+    Generate vs Validation: this library models schema GENERATE only. Authoring
+    validation against generated XSDs (--no-xsd / xsdValidation) lives in
+    org.blockml.bml.cli ScopeExclusions — never as an XSD target capability.
+
+    Pipeline: ResolveOptions → EmitBlockXsd [+ EmitTypesXsd / EmitServiceXsd] →
+    EmitCatalogXml → files under outDir plus rootFiles catalog.xml.
+    Host CLI wiring (default outDir schemas/, write) lives in org.blockml.bml.cli.*</documentation>
+  <references>
+    <see type="xsddocumentation:LayerSeparation" relation="ReadNext"></see>
+    <see type="xsdcap:Render" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/documentation/LayerSeparation.bml

@@ -0,0 +1,42 @@
+<!--
+  XSD Documentation — LayerSeparation
+  FQN: org.blockml.bml.target.xsd.documentation.LayerSeparation
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>LayerSeparation</name>
+  <type>xsddocumentation:LayerSeparation</type>
+  <baseType>core:Documentation</baseType>
+  <is>What this library owns versus neighbors</is>
+
+  <documentation>Layers:
+    • org.blockml.bml.definition / docs 19 D1 — bml:xml particle grammar SSOT (XSD consumes)
+    • org.blockml.bml.target.xsd.* (this library) — emit bml.xsd / types.xsd / service.xsd / catalog
+    • org.blockml.bml.cli.* — default outDir=schemas, rootFiles write, --no-xsd authoring validation
+    • MachineBlocks domain XSDs — out of scope (product schemas)
+
+    Do not double-maintain CLI flags or D1 grammar here; link via SeeAlso.</documentation>
+  <references>
+    <see type="xsddocumentation:ArchitectureOverview" relation="ReadNext"></see>
+    <see type="cli:Library" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/documentation/PackageOwnership.bml

@@ -0,0 +1,43 @@
+<!--
+  XSD Documentation — PackageOwnership
+  FQN: org.blockml.bml.target.xsd.documentation.PackageOwnership
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>PackageOwnership</name>
+  <type>xsddocumentation:PackageOwnership</type>
+  <baseType>core:Documentation</baseType>
+  <is>What belongs in @blockml/xsd-target vs neighbors</is>
+
+  <documentation>Owns: registry name xsd, accepts, Options, emit of bml.xsd/types.xsd/service.xsd/catalog.xml,
+    D1 hardcoded lists + registry extras, MemberPrefersElement, NS/FQN constants.
+
+    Does not own: CLI default outDir=schemas, rootFiles write, exit codes (cli);
+    D1/bml:xml grammar SSOT (Definition / docs 19);
+    --no-xsd / xsdValidation (cli ScopeExclusion);
+    MachineBlocks domain XSDs.
+    Phase C IDE catalog narrative pointers in docs 15 stay host docs; generation here.</documentation>
+  <references>
+    <see type="xsddocumentation:ScopeExclusions" relation="ReadNext"></see>
+    <see type="cli:Library" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/documentation/ParticleMappingRules.bml

@@ -0,0 +1,49 @@
+<!--
+  XSD Documentation — ParticleMappingRules
+  FQN: org.blockml.bml.target.xsd.documentation.ParticleMappingRules
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>ParticleMappingRules</name>
+  <type>xsddocumentation:ParticleMappingRules</type>
+  <baseType>core:Documentation</baseType>
+  <is>bml.xsd particle construction (XSD4–XSD11)</is>
+
+  <documentation>Consumes D1 / bml:xml grammar from Definition (docs 19); does not redefine it.
+
+    XSD4: targetNamespace http://blockml.org/bml; single root element block; mixed=true.
+    XSD5: choice of unbounded optional xs:element particles only.
+    XSD6: no element-level xs:any.
+    XSD7: anyAttribute processContents=lax.
+    XSD8: D1_IDENTITY_ELEMENTS and D1_CONTAINER_ELEMENTS hardcoded sorted unique.
+    XSD9: ExtraElementNames from META_DEFINITION_FQNS via MemberPrefersElement.
+    XSD10: MemberPrefersElement — element/raw element true; sole attribute false;
+    aggregations/associations true; default true.
+    XSD11: extras exclude names already in D1 identity or containers.
+
+    Later: full D1 fidelity (attributes, text, nested models); pure Definition-driven lists.</documentation>
+  <references>
+    <see type="xsddocumentation:DomainVocabularyRules" relation="ReadNext"></see>
+    <see type="xsdcap:EmitBlockXsd" relation="SeeAlso"></see>
+    <see type="def:BlockDefinition" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/xsd/documentation/PublicApi.bml

@@ -0,0 +1,45 @@
+<!--
+  XSD Documentation — PublicApi
+  FQN: org.blockml.bml.target.xsd.documentation.PublicApi
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:xsd="org.blockml.bml.target.xsd"
+  xmlns:xsdapi="org.blockml.bml.target.xsd.api"
+  xmlns:xsdcap="org.blockml.bml.target.xsd.capability"
+  xmlns:xsdconfig="org.blockml.bml.target.xsd.config"
+  xmlns:xsddocumentation="org.blockml.bml.target.xsd.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>PublicApi</name>
+  <type>xsddocumentation:PublicApi</type>
+  <baseType>core:Documentation</baseType>
+  <is>Public TypeScript surface mirrored in this library</is>
+
+  <documentation>Exports (packages/xsd-target/src/index.ts):
+    XsdTarget, XsdRenderOutput; XsdOptions, resolveXsdOptions, DEFAULT_XSD_OPTIONS;
+    emitBlockXsd, emitTypesXsd, emitServiceXsd; emitCatalogXml, catalogRelativePath, CatalogEntry;
+    BML_DOCUMENT_NS, BML_TYPES_NS, BML_SERVICE_NS, TYPE_FQN_PREFIX, SERVICE_FQN_PREFIX.
+
+    Modeled as: api/XsdOptions, XsdRenderOutput, CatalogEntry; config/XsdConstants,
+    DefaultXsdOptions; capabilities listed on Library.blocks.
+    Defines relation: this doc ↔ Options and Render.</documentation>
+  <references>
+    <see type="xsddocumentation:ParticleMappingRules" relation="ReadNext"></see>
+    <see type="xsdapi:XsdOptions" relation="SeeAlso"></see>
+    <see type="xsdcap:Render" relation="SeeAlso"></see>
+    <see type="xsdconfig:DefaultXsdOptions" relation="SeeAlso"></see>
+  </references>
+
+</block>