@blockml/parser 0.9.4 → 0.9.6

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

@@ -1,12 +1,6 @@
-<!--
-  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
-                      "
+<!--Parser Documentation — DesignDecisions
+  FQN: org.blockml.bml.compiler.parser.documentation.DesignDecisions-->
+<pardocumentation:DesignDecisions xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,14 +24,16 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>DesignDecisions</name>
-  <type>pardocumentation:DesignDecisions</type>
-  <baseType>core:Documentation</baseType>
-  <is>Normative parser design decisions</is>
-
-  <documentation><![CDATA[
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Normative parser design decisions
+  </is>
+  <documentation>
+    <![CDATA[
     # Normative parser design decisions
-
+    
     - B2: unknown bml:* → error at map (BML_UNKNOWN_DIRECTIVE); unknown instance members → validator error (BML_UNKNOWN_PROPERTY).
     - B3: inputType/outputType → TypeExpression at map time.
     - B4: ExpressionValue.raw only; AST via core utility.
@@ -51,12 +47,11 @@
     - 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.
+    - B25: store xmlns:xsi + schemaLocation on SourceInfo; record rootForm (block vs type-as-root).
     - B26: parse() entry; types in @blockml/bom.
-  ]]></documentation>
-
+    ]]>
+  </documentation>
   <references>
     <see type="pardocumentation:RoundtripContract" relation="ReadNext" />
   </references>
-
-</block>
+</pardocumentation:DesignDecisions>

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

@@ -1,12 +1,6 @@
-<!--
-  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
-                      "
+<!--Parser Documentation — Diagnostics
+  FQN: org.blockml.bml.compiler.parser.documentation.Diagnostics-->
+<pardocumentation:Diagnostics xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,18 +24,24 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   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><![CDATA[Pipeline hard-fail codes (parse.ts):
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Map-time and pipeline diagnostic codes
+  </is>
+  <documentation>
+    <![CDATA[
+    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
-
+    • BML_INVALID_ROOT — not <block> and not a type-as-root tag (doc:DocumentFormat)
+    • BML_MISSING_BLOCK_TYPE — legacy <block> supplies neither root tag type nor <type>
+    • BML_MISSING_EMBEDDED_BLOCK_TYPE — legacy embed <block> supplies neither tag type nor <type>
+    • BML_MISSING_SUBBLOCK_NAME — legacy Sub-Block <block> supplies neither tag name nor <name>
+    • BML_MAP_ERROR — mapping exception, including tag vs child <type>/<name> mismatch
+    
     Map-time codes (mapper modules):
     • BML_UNKNOWN_NAMESPACE_PREFIX, BML_UNQUALIFIED_BLOCK_REFERENCE
     • BML_UNKNOWN_TYPE — type expression parse failure
@@ -53,18 +53,19 @@
     • BML_NESTED_COMPOSITION — <composition> inside an aggregation that is already nested in a composition
     • BML_DUPLICATE_COMPOSITION — more than one <composition> on the same aggregation member
     • BML_DUPLICATE_PROPERTY_VALUE — more than one <value> for the same namespace on a property
+    • BML_MIXED_MEMBER_VALUE — instance member mixes attribute + element, compact JSON list + repeated tags, or a non-literal with another payload
     • BML_UNEXPECTED_TEXT — non-whitespace text on an element-only grammar node
     • BML_INVALID_VALUE — optional parseValue hook rejected a literal (value stays a string)
-
+    
     Map-time diagnostics attach Diagnostic.source to the use-site token when known
     (attribute value or first occurrence in the throwing element), not the document root.
-
+    
     Host policy: whether to abort after diagnostics is orchestrator decision.
-    Diagnostic type: org.blockml.bml.bom.common.Diagnostic.]]></documentation>
-
+    Diagnostic type: org.blockml.bml.bom.common.Diagnostic.
+    ]]>
+  </documentation>
   <references>
     <see type="parconfig:MapTimeDiagnosticCodes" relation="Defines" />
     <see type="pardocumentation:PackageOwnership" relation="ReadNext" />
   </references>
-
-</block>
+</pardocumentation:Diagnostics>

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

@@ -1,12 +1,6 @@
-<!--
-  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
-                      "
+<!--Parser Documentation — ExpressionCapture
+  FQN: org.blockml.bml.compiler.parser.documentation.ExpressionCapture-->
+<pardocumentation:ExpressionCapture xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,24 +24,27 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   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 }.
-    Mixed text with ${ … } holes → InterpolatedTextValue { raw, source }.
-    Implementation CDATA → embeddedExpressions[] with source offsets.
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Raw expression storage — no AST in Urmodell (B4)
+  </is>
+  <documentation>
+    ${ … } attribute/element values → ExpressionValue { raw, source }.
+    Mixed text with unescaped ${ … } holes → InterpolatedTextValue { raw, source }.
+    `\${` is a literal `${` (odd backslashes immediately before `$`). A value whose
+    only openers are escaped is LiteralValue after unescape — BOM stores `${`, not
+    `\${`. Implementation CDATA → embeddedExpressions[] with source offsets.
+    
     Parser step [5] captures raw text only. AST construction via parseExpression()
     / parseInterpolatedText() in @blockml/framework (Stage 2 utility) — never stored
     on Urmodell.
-
-    inputType/outputType on capabilities → TypeExpression at map time (B3).</documentation>
-
+    
+    inputType/outputType on capabilities → TypeExpression at map time (B3).
+  </documentation>
   <references>
     <see type="pardocumentation:SingleFileScope" relation="ReadNext" />
     <see type="parcap:ExpressionFromRaw" relation="SeeAlso" />
   </references>
-
-</block>
+</pardocumentation:ExpressionCapture>

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

@@ -1,12 +1,6 @@
-<!--
-  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
-                      "
+<!--Parser Documentation — Introduction
+  FQN: org.blockml.bml.compiler.parser.documentation.Introduction-->
+<pardocumentation:Introduction xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,28 +24,29 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   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).
+  <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>
-
+    depend on @blockml/serializer, @blockml/validator, or TypeRegistry bootstrap.
+  </documentation>
   <references>
     <see type="pardocumentation:LayerSeparation" relation="ReadNext" />
     <see type="bomdocumentation:Introduction" relation="SeeAlso" />
   </references>
-
-</block>
+</pardocumentation:Introduction>

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

@@ -1,12 +1,6 @@
-<!--
-  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
-                      "
+<!--Parser Documentation — LayerSeparation
+  FQN: org.blockml.bml.compiler.parser.documentation.LayerSeparation-->
+<pardocumentation:LayerSeparation xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,31 +24,32 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   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:
-
+  <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>
-
+    Parser stores ExpressionValue.raw only (B4); never writes AST to Urmodell.
+  </documentation>
   <references>
     <see type="pardocumentation:ArchitectureOverview" relation="ReadNext" />
     <see type="bomdocumentation:LayerSeparation" relation="SeeAlso" />
   </references>
-
-</block>
+</pardocumentation:LayerSeparation>

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

@@ -1,12 +1,6 @@
-<!--
-  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
-                      "
+<!--Parser Documentation — MappingPrinciples
+  FQN: org.blockml.bml.compiler.parser.documentation.MappingPrinciples-->
+<pardocumentation:MappingPrinciples xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,24 +24,25 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   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
+  <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>
-
+    block rendering. Maximum authored surface: store as much as Urmodell can carry.
+  </documentation>
   <references>
     <see type="pardocumentation:MemberMappingOrder" relation="ReadNext" />
     <see type="bomdocumentation:AbstractionPrinciple" relation="SeeAlso" />
   </references>
-
-</block>
+</pardocumentation:MappingPrinciples>

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

@@ -1,12 +1,6 @@
-<!--
-  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
-                      "
+<!--Parser Documentation — MemberMapping
+  FQN: org.blockml.bml.compiler.parser.documentation.MemberMapping-->
+<pardocumentation:MemberMapping xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,18 +24,33 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   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><![CDATA[Property/aggregation/association/capability members:
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Member definition and composition mapping
+  </is>
+  <documentation>
+    <![CDATA[
+    Property/aggregation/association/capability members:
     • Element QName = member identity (deprecated namespace= attr → error)
     • type attribute → TypeExpression; value/memberValues for properties
     • One <value> per namespace on a property member. Unprefixed <value> /
       value="…" is the canonical namespace (""). Prefixed <prefix:value>
       (Annotation xmlns) is a separate facet. Extra copies of the same
-      namespace → BML_DUPLICATE_PROPERTY_VALUE.
+      namespace → BML_DUPLICATE_PROPERTY_VALUE. A list default is one
+      <value>['a', 'b']</value> — not stacked <value> (choice-list reading;
+      use suggestions).
+    • Collection instance values (type multiplicity [] / 0..n) — properties
+      and associations share two forms. Compact: one attribute or element
+      whose text is a JSON-like array of quoted items
+      (myText="['Hello', 'Good Bye']", myAsso="['myId', 'otherId']").
+      Verbose: one instance element per item in document order
+      (<myText>Hello</myText><myText>Good Bye</myText>,
+      <myAsso>myId</myAsso><myAsso>otherId</myAsso>). A single item stays
+      without brackets (myAsso="myId"). Do not mix attribute + element,
+      compact JSON + repeated tags, or space-separated tokens
+      → BML_MIXED_MEMBER_VALUE. Duplicate XML attributes are not a list form.
     • One <composition> per aggregation member on a Block definition, as a direct
       child of that member (not of <block>, <aggregations>, nested inside metadata,
       or inside an aggregation that is already nested in a composition). Extra
@@ -56,12 +65,12 @@
       explicit type:TypeReferenceEntity); bound B = core:Exception
     • 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>
-
+    
+    Directives on composition: bml:each, bml:if, bml:unless, bml:with — stored unexpanded.
+    ]]>
+  </documentation>
   <references>
     <see type="pardocumentation:ExpressionCapture" relation="ReadNext" />
     <see type="parcap:MapBlockInstanceNode" relation="SeeAlso" />
   </references>
-
-</block>
+</pardocumentation:MemberMapping>

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

@@ -1,12 +1,6 @@
-<!--
-  Parser Documentation — MemberMappingOrder
-  FQN: org.blockml.bml.compiler.parser.documentation.MemberMappingOrder
--->
-<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
-                      "
+<!--Parser Documentation — MemberMappingOrder
+  FQN: org.blockml.bml.compiler.parser.documentation.MemberMappingOrder-->
+<pardocumentation:MemberMappingOrder xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,22 +24,23 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>MemberMappingOrder</name>
-  <type>pardocumentation:MemberMappingOrder</type>
-  <baseType>core:Documentation</baseType>
-  <is>BML document order preserved in members[]</is>
-
-  <documentation>Append to members[] in BML document order — the order elements appear in source.
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    BML document order preserved in members[]
+  </is>
+  <documentation>
+    Append to members[] in BML document order — the order elements appear in source.
+    
     • Element localName = member name (no name= attribute on member elements)
     • MUST NOT sort by name, kind, or type
     • Ordinal = index in members[] — roundtrip must preserve array order
     • Parser accepts any authored sibling order; serializer emits canonical order (B12)
-
-    Inside containers (properties/aggregations/…): filter by kind, keep BOM array order.</documentation>
-
+    
+    Inside containers (properties/aggregations/…): filter by kind, keep BOM array order.
+  </documentation>
   <references>
     <see type="pardocumentation:AttributeClassification" relation="ReadNext" />
   </references>
-
-</block>
+</pardocumentation:MemberMappingOrder>

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

@@ -1,12 +1,6 @@
-<!--
-  Parser Documentation — PackageOwnership
-  FQN: org.blockml.bml.compiler.parser.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
-                      "
+<!--Parser Documentation — PackageOwnership
+  FQN: org.blockml.bml.compiler.parser.documentation.PackageOwnership-->
+<pardocumentation:PackageOwnership xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,26 +24,27 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>PackageOwnership</name>
-  <type>pardocumentation:PackageOwnership</type>
-  <baseType>core:Documentation</baseType>
-  <is>Toolchain package responsibilities for parsing</is>
-
-  <documentation>@blockml/parser — BML XML → BomDocument; parse() → ParseResult.
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Toolchain package responsibilities for parsing
+  </is>
+  <documentation>
+    @blockml/parser — BML XML → BomDocument; parse() → ParseResult.
     Owns mapping algorithm, Stage 1 pipeline [1]–[5], this BML library.
-
+    
     @blockml/bom — Urmodell types, ParseOptions/ParseResult (B26), Diagnostic,
     bomEquals/stripProvenance (B20). Parser produces; does not redefine.
-
+    
     @blockml/framework — TypeRegistry, parseExpression(), Definition meta-model, validateTypes.
     Parser consumes implicit namespace rules; defers AST and semantic validation.
-
+    
     @blockml/serializer — BOM → BML inverse. @blockml/validator — Stage 2 checks.
-    @blockml/cli — TypeRegistry bootstrap and orchestration.</documentation>
-
+    @blockml/cli — TypeRegistry bootstrap and orchestration.
+  </documentation>
   <references>
     <see type="pardocumentation:ScopeExclusions" relation="ReadNext" />
     <see type="bomdocumentation:PackageOwnership" relation="SeeAlso" />
   </references>
-
-</block>
+</pardocumentation:PackageOwnership>

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

@@ -1,12 +1,6 @@
-<!--
-  Parser Documentation — PublicApi
-  FQN: org.blockml.bml.compiler.parser.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
-                      "
+<!--Parser Documentation — PublicApi
+  FQN: org.blockml.bml.compiler.parser.documentation.PublicApi-->
+<pardocumentation:PublicApi xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,13 +24,16 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>PublicApi</name>
-  <type>pardocumentation:PublicApi</type>
-  <baseType>core:Documentation</baseType>
-  <is>parse() entry point (B26)</is>
-
-  <documentation><![CDATA[parse(source: string, options?: ParseOptions): ParseResult
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    parse() entry point (B26)
+  </is>
+  <documentation>
+    <![CDATA[
+    parse(source: string, options?: ParseOptions): ParseResult
+    
     ParseOptions (owned by @blockml/bom):
     • filePath — default "<memory>"; written to BomDocument.source.filePath
     • continueOnError — default true; keep mapping after errors when possible
@@ -44,12 +41,12 @@
       registry bootstrap). When set, scalar member values use the hook only;
       Boolean/number heuristics run only during bootstrap (no hook). Expression
       and interpolation classification always run.
-
+    
     ParseResult (owned by @blockml/bom):
     • document — BomDocument | null (null on hard fail)
     • diagnostics — Diagnostic[]
     • success — false if any diagnostic has severity === "error"
-
+    
     Behaviour:
     • B24 detect → [2] xmldom → [3]–[5] map
     • Hard fail → document: null (unsupported format, missing root, invalid root)
@@ -57,13 +54,13 @@
       carries a span; otherwise BML_MAP_ERROR at 1:1. continueOnError still returns
       document when possible
     • Sync only; no throw on recoverable errors
-    • Does NOT call validator; does NOT expand directives]]></documentation>
-
+    • Does NOT call validator; does NOT expand directives
+    ]]>
+  </documentation>
   <references>
     <see type="bomapi:ParseOptions" relation="Defines" />
     <see type="bomapi:ParseResult" relation="Defines" />
     <see type="parcap:Parse" relation="Defines" />
     <see type="pardocumentation:MappingPrinciples" relation="ReadNext" />
   </references>
-
-</block>
+</pardocumentation:PublicApi>