@blockml/parser 0.1.0

package/blocks/org/blockml/bml/compiler/parser/config/MapTimeDiagnosticCodes.bml

@@ -0,0 +1,40 @@
+<!--
+  Parser — MapTimeDiagnosticCodes
+  FQN: org.blockml.bml.compiler.parser.config.MapTimeDiagnosticCodes
+-->
+<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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>MapTimeDiagnosticCodes</name>
+  <type>parconfig:MapTimeDiagnosticCodes</type>
+  <baseType>parser:ParserType</baseType>
+  <is>Diagnostic codes emitted during parse pipeline and mapping</is>
+
+  <documentation>Hard-fail codes return document: null. Map-time codes may attach to ParseResult with continueOnError.</documentation>
+
+  <properties>
+    <codes type="type:Text[]">
+      <documentation>Ordered: BML_UNSUPPORTED_FORMAT, BML_MALFORMED_XML, BML_MISSING_ROOT, BML_INVALID_ROOT, BML_MAP_ERROR, BML_UNKNOWN_NAMESPACE_PREFIX, BML_UNQUALIFIED_BLOCK_REFERENCE, BML_UNKNOWN_TYPE (required)</documentation>
+    </codes>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/compiler/parser/config/ParserConstants.bml

@@ -0,0 +1,49 @@
+<!--
+  Parser — ParserConstants
+  FQN: org.blockml.bml.compiler.parser.config.ParserConstants
+-->
+<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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>ParserConstants</name>
+  <type>parconfig:ParserConstants</type>
+  <baseType>parser:ParserType</baseType>
+  <is>Well-known URIs and V1 root element name</is>
+
+  <documentation>Shared across pipeline, qname resolution, and namespace extraction.</documentation>
+
+  <properties>
+    <XSI_NS type="type:Text">
+      <documentation>XSI_NS. TS type: type:Text. (required)</documentation>
+    </XSI_NS>
+    <BML_XMLNS type="type:Text">
+      <documentation>BML_XMLNS. TS type: type:Text. (required)</documentation>
+    </BML_XMLNS>
+    <TYPE_REFERENCE_ENTITY type="type:Text">
+      <documentation>TYPE_REFERENCE_ENTITY. TS type: type:Text. (required)</documentation>
+    </TYPE_REFERENCE_ENTITY>
+    <V1_ROOT_ELEMENT type="type:Text">
+      <documentation>V1_ROOT_ELEMENT. TS type: type:Text. (required)</documentation>
+    </V1_ROOT_ELEMENT>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/compiler/parser/documentation/ArchitectureOverview.bml

@@ -0,0 +1,61 @@
+<!--
+  Parser Documentation — ArchitectureOverview
+  FQN: org.blockml.bml.compiler.parser.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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>ArchitectureOverview</name>
+  <type>pardocumentation:ArchitectureOverview</type>
+  <baseType>core:Documentation</baseType>
+  <is>Parse pipeline [1]–[5] and module decomposition</is>
+
+  <documentation>Entry point: parse(source, options?) → ParseResult (B26).
+
+    Stage 1 pipeline:
+    [1] Format detect (B24) — detectFormat(); strip UTF-8 BOM; first '<' → xml
+    [2] XML DOM (B18) — parseXmlDom() via @xmldom/xmldom
+    [3] Root type resolver — assertBlockRoot(); V1: <block> only
+    [4] Namespace resolver — extractNamespaceBindings(), mergeSourceInfo(); FQN resolution
+    [5] BML → BOM mapper — mapDocumentBlock() → BomDocument
+
+    Module decomposition (packages/parser/src/):
+    • parse.ts → parcap:Parse orchestrates [1]–[5]
+    • pipeline/format-detect.ts → parcap:DetectFormat
+    • pipeline/xml-dom.ts → parcap:ParseXmlDom, GetParseErrors, DocumentElement
+    • pipeline/root-type.ts → parcap:AssertBlockRoot
+    • pipeline/namespaces.ts → parcap:ExtractNamespaceBindings, MergeSourceInfo
+    • map/context.ts → parmap:MapContext, parcap:CreateMapContext
+    • map/map-block.ts → parcap:MapDocumentBlock, MapBlock
+    • map/map-composition.ts → composition tree mapping
+    • map/type-expression.ts → parcap:ParseTypeExpression
+    • map/member-value.ts → parcap:ParseMemberValue
+    • map/directives.ts → parcap:ParseDirectives, ParseBmlMeta
+    • util/* → visibility, boolean, qname, xml helpers</documentation>
+
+  <references>
+    <see type="pardocumentation:V1Scope" relation="ReadNext"></see>
+    <see type="parcap:Parse" relation="Defines"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/parser/documentation/AttributeClassification.bml

@@ -0,0 +1,56 @@
+<!--
+  Parser Documentation — AttributeClassification
+  FQN: org.blockml.bml.compiler.parser.documentation.AttributeClassification
+-->
+<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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>AttributeClassification</name>
+  <type>pardocumentation:AttributeClassification</type>
+  <baseType>core:Documentation</baseType>
+  <is>Fixed priority chain for XML attributes (Rules 1–3)</is>
+
+  <documentation>When mapping an XML element, every attribute is classified — first matching rule wins:
+
+    Rule 1 — XML infrastructure:
+    • xmlns* → SourceInfo.namespaceBindings (incl. xmlns:xsi — B25)
+    • xsi:schemaLocation / xsi:noNamespaceSchemaLocation → SourceInfo (B25)
+    • other xsi:* → ignore (not memberValues)
+
+    Rule 2 — bml:* attributes:
+    • Composition meta (bml:id, bml:version, …) → BlockInstance fields
+    • Directives (bml:each, bml:if, …) → directives[]
+    • Unknown bml:* → BML_UNKNOWN_DIRECTIVE (error at map time — B2)
+
+    Rule 3 — All other attributes:
+    • memberValues[name] (camelCase)
+    • ${ expr } → ExpressionValue { raw } (B4)
+
+    Serialize side of Rule 1 (B25 re-emit) → @blockml/serializer.</documentation>
+
+  <references>
+    <see type="pardocumentation:XmlCommentsParse" relation="ReadNext"></see>
+    <see type="parcap:ParseDirectives" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/parser/documentation/BlockMetadataMapping.bml

@@ -0,0 +1,51 @@
+<!--
+  Parser Documentation — BlockMetadataMapping
+  FQN: org.blockml.bml.compiler.parser.documentation.BlockMetadataMapping
+-->
+<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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>BlockMetadataMapping</name>
+  <type>pardocumentation:BlockMetadataMapping</type>
+  <baseType>core:Documentation</baseType>
+  <is>Block definition metadata field mapping</is>
+
+  <documentation>Map <block> child elements to BlockDefinition fields:
+
+    Identity: name, type, baseType, is, isNot, version, definition
+    Structural: since, status, summary, documentation, abstract, final
+    Aggregations: keywords, changelog, examples, references, constraints, aliases,
+    language, genericTypes, contracts, properties, aggregations, associations,
+    capabilities, subBlocks, embeddedBlocks
+
+    • xmlRendering (bml:xml metadata) stored on BlockDefinition — NOT in directives[] (B23/D3)
+    • authoredPlacement stored for dual element|attribute forms (D9)
+    • authoredCharacterDataForm for text vs CDATA (D8)
+    • Visibility prefixes stripped → logical name + visibility (B14 parse half)</documentation>
+
+  <references>
+    <see type="pardocumentation:MemberMapping" relation="ReadNext"></see>
+    <see type="def:BlockDefinition" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/parser/documentation/DesignDecisions.bml

@@ -0,0 +1,53 @@
+<!--
+  Parser Documentation — DesignDecisions
+  FQN: org.blockml.bml.compiler.parser.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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>DesignDecisions</name>
+  <type>pardocumentation:DesignDecisions</type>
+  <baseType>core:Documentation</baseType>
+  <is>Normative parser design decisions</is>
+
+  <documentation>B2: unknown bml:* → error at map; unknown custom props → validator warning.
+    B3: inputType/outputType → TypeExpression at map time.
+    B4: ExpressionValue.raw only; AST via core utility.
+    B5: single-file parser scope.
+    B6: JSON not planned.
+    B7/B8: Phase A slice; XSD not Stage 1.
+    B11: XML comments bound to elements (parse side).
+    B14: strip _/__ → logical name + visibility.
+    B15/B16: boolean values vs type refs.
+    B18: @xmldom/xmldom for DOM.
+    B19: redundant aggregation type — map must not apply.
+    B23: preserve xmlRendering + D6 recipe at Stage 1.
+    B24: format detector (BOM strip, first '<').
+    B25: store xmlns:xsi + schemaLocation on SourceInfo.
+    B26: parse() entry; types in @blockml/bom.</documentation>
+
+  <references>
+    <see type="pardocumentation:RoundtripContract" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/parser/documentation/Diagnostics.bml

@@ -0,0 +1,52 @@
+<!--
+  Parser Documentation — Diagnostics
+  FQN: org.blockml.bml.compiler.parser.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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>Diagnostics</name>
+  <type>pardocumentation:Diagnostics</type>
+  <baseType>core:Documentation</baseType>
+  <is>Map-time and pipeline diagnostic codes</is>
+
+  <documentation>Pipeline hard-fail codes (parse.ts):
+    • BML_UNSUPPORTED_FORMAT — format detect failed
+    • BML_MALFORMED_XML — DOM parse error
+    • BML_MISSING_ROOT — no document element
+    • BML_INVALID_ROOT — not <block> (V1)
+    • BML_MAP_ERROR — mapping exception
+
+    Map-time codes (mapper modules):
+    • BML_UNKNOWN_NAMESPACE_PREFIX, BML_UNQUALIFIED_BLOCK_REFERENCE
+    • BML_UNKNOWN_TYPE — type expression parse failure
+
+    Host policy: whether to abort after diagnostics is orchestrator decision.
+    Diagnostic type: org.blockml.bml.bom.common.Diagnostic.</documentation>
+
+  <references>
+    <see type="parconfig:MapTimeDiagnosticCodes" relation="Defines"></see>
+    <see type="pardocumentation:PackageOwnership" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/parser/documentation/ExpressionCapture.bml

@@ -0,0 +1,46 @@
+<!--
+  Parser Documentation — ExpressionCapture
+  FQN: org.blockml.bml.compiler.parser.documentation.ExpressionCapture
+-->
+<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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>ExpressionCapture</name>
+  <type>pardocumentation:ExpressionCapture</type>
+  <baseType>core:Documentation</baseType>
+  <is>Raw expression storage — no AST in Urmodell (B4)</is>
+
+  <documentation>${ … } attribute/element values → ExpressionValue { raw, source }.
+    Implementation CDATA → embeddedExpressions[] with source offsets.
+
+    Parser step [5] captures raw text only. AST construction via parseExpression()
+    in @blockml/core (Stage 2 utility) — never stored on Urmodell.
+
+    inputType/outputType on capabilities → TypeExpression at map time (B3).</documentation>
+
+  <references>
+    <see type="pardocumentation:SingleFileScope" relation="ReadNext"></see>
+    <see type="parcap:ExpressionFromRaw" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/parser/documentation/Introduction.bml

@@ -0,0 +1,52 @@
+<!--
+  Parser Documentation — Introduction
+  FQN: org.blockml.bml.compiler.parser.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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>Introduction</name>
+  <type>pardocumentation:Introduction</type>
+  <baseType>core:Documentation</baseType>
+  <is>Purpose and scope of the Parser package</is>
+
+  <documentation>The @blockml/parser package converts BML XML source to BomDocument (Urmodell).
+    It is the forward mapping — enabling BML → BOM → BML roundtrip together with @blockml/serializer.
+
+    This library (org.blockml.bml.compiler.parser.*) is the SSOT. TypeScript in
+    packages/parser/src/ implements it. Parity tests in packages/parser/test/
+    verify BML ↔ TS alignment.
+
+    V1 build order: parser and serializer prove BML ↔ BOM roundtrip first; validator
+    and compiler follow. Single-file scoped — one parse() invocation → one BomDocument.
+
+    Pipeline placement: BML XML → Parser → BomDocument; consumed by serializer, validator,
+    compiler, LSP. Depends on @blockml/bom (types) and @xmldom/xmldom (B18). Does not
+    depend on @blockml/serializer, @blockml/validator, or TypeRegistry bootstrap.</documentation>
+
+  <references>
+    <see type="pardocumentation:LayerSeparation" relation="ReadNext"></see>
+    <see type="bomdocumentation:Introduction" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/parser/documentation/LayerSeparation.bml

@@ -0,0 +1,55 @@
+<!--
+  Parser Documentation — LayerSeparation
+  FQN: org.blockml.bml.compiler.parser.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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>LayerSeparation</name>
+  <type>pardocumentation:LayerSeparation</type>
+  <baseType>core:Documentation</baseType>
+  <is>Parser vs BOM vs core vs serializer vs validator</is>
+
+  <documentation>Five layers relevant to parsing:
+
+    org.blockml.bml.bom.* (@blockml/bom) — Urmodell data structures the parser produces
+    (BomDocument, BlockDefinition, MemberDefinition, …). ParseOptions and ParseResult (B26).
+
+    org.blockml.bml.compiler.parser.* (this package) — BML → BOM mapping algorithm,
+    Stage 1 pipeline [1]–[5], parse() entry point contract.
+
+    org.blockml.bml.definition.* (@blockml/core) — BML meta-model. Parser links to Definition
+    blocks for canonical paths; does not duplicate language grammar.
+
+    org.blockml.bml.compiler.serializer.* (@blockml/serializer) — inverse mapping (BOM → BML).
+    Emit rules B12–B25 live there, not here.
+
+    @blockml/framework utilities — parseExpression() (Stage 2 AST), TypeRegistry, validateTypes.
+    Parser stores ExpressionValue.raw only (B4); never writes AST to Urmodell.</documentation>
+
+  <references>
+    <see type="pardocumentation:ArchitectureOverview" relation="ReadNext"></see>
+    <see type="bomdocumentation:LayerSeparation" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/parser/documentation/MappingPrinciples.bml

@@ -0,0 +1,48 @@
+<!--
+  Parser Documentation — MappingPrinciples
+  FQN: org.blockml.bml.compiler.parser.documentation.MappingPrinciples
+-->
+<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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>MappingPrinciples</name>
+  <type>pardocumentation:MappingPrinciples</type>
+  <baseType>core:Documentation</baseType>
+  <is>Fundamental mapping rule — structure + preservation</is>
+
+  <documentation>BML → BOM → BML must always be possible. The mapper preserves authored structure
+    and values — directives, aggregation declarations, literal syntax, unresolved type
+    references, namespace bindings, and bml:xml metadata.
+
+    Mapper responsibility: structure + classification + preservation.
+    NOT mapper responsibility: canonicalization, expansion, merge, evaluation.
+
+    BOM makes no statement about directive expansion, aggregation interpretation, or
+    block rendering. Maximum authored surface: store as much as Urmodell can carry.</documentation>
+
+  <references>
+    <see type="pardocumentation:MemberMappingOrder" relation="ReadNext"></see>
+    <see type="bomdocumentation:AbstractionPrinciple" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/parser/documentation/MemberMapping.bml

@@ -0,0 +1,48 @@
+<!--
+  Parser Documentation — MemberMapping
+  FQN: org.blockml.bml.compiler.parser.documentation.MemberMapping
+-->
+<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:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:parcap="org.blockml.bml.compiler.parser.capability"
+  xmlns:parconfig="org.blockml.bml.compiler.parser.config"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:parmap="org.blockml.bml.compiler.parser.map"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>MemberMapping</name>
+  <type>pardocumentation:MemberMapping</type>
+  <baseType>core:Documentation</baseType>
+  <is>Member definition and composition mapping</is>
+
+  <documentation>Property/aggregation/association/capability members:
+    • Element QName = member identity (deprecated namespace= attr → error)
+    • type attribute → TypeExpression; value/memberValues for properties
+    • Composition under aggregation member elements (not standalone <composition>)
+    • Constraints/suggestions → BlockInstance[] in document order
+    • Sub-Blocks and embedded blocks → nested BlockDefinition trees
+    • Redundant aggregation type on override → validator warning B19; parser must not apply
+
+    Directives on composition: bml:each, bml:if, bml:unless, bml:with — stored unexpanded.</documentation>
+
+  <references>
+    <see type="pardocumentation:ExpressionCapture" relation="ReadNext"></see>
+    <see type="parcap:MapBlockInstanceNode" relation="SeeAlso"></see>
+  </references>
+
+</block>