@blockml/framework 0.9.4 → 0.9.6

package/blocks/org/blockml/bml/framework/documentation/Diagnostics.bml

@@ -1,12 +1,6 @@
-<!--
-  Framework Documentation — Diagnostics
-  FQN: org.blockml.bml.framework.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
-                      "
+<!--Framework Documentation — Diagnostics
+  FQN: org.blockml.bml.framework.documentation.Diagnostics-->
+<fwdocumentation:Diagnostics xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -32,65 +26,69 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>Diagnostics</name>
-  <type>fwdocumentation:Diagnostics</type>
-  <baseType>core:Documentation</baseType>
-  <is>Framework diagnostic codes</is>
-
-  <documentation>Diagnostic codes emitted by framework utilities (see fwconfig:FrameworkDiagnosticCodes):
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Framework diagnostic codes
+  </is>
+  <documentation>
+    Diagnostic codes emitted by framework utilities (see fwconfig:FrameworkDiagnosticCodes):
+    
     validateTypes (type-driven reference walk — declared ValueType, never the field name):
     • BML_UNKNOWN_BASE_TYPE — baseType FQN not in TypeRegistry (at baseTypeSource)
     • BML_UNKNOWN_CONTRACT — contracts[] FQN not in TypeRegistry
     • BML_UNKNOWN_TYPE — TypeReference / TypeReferenceEntity value, PackageReference, see type=/relation=/language=, member types, groups, language — FQN or package not in TypeRegistry and not a well-known primitive. Authored QNames / TypeExpressions on TypeReference values resolve via document.source.namespaceBindings before the lookup; the canonical default is reported once (value, not also values[namespace=""])
     • BML_UNKNOWN_PROPERTY — PropertyReference / AggregationReference / AssociationReference / CapabilityReference path does not resolve (or BML_UNKNOWN_TYPE if the owning type cannot be resolved)
-    • BML_UNRESOLVABLE_INSTANCE_REF — InstanceReference / InstanceReferenceEntity value does not resolve to a document instance id
+    • BML_UNRESOLVABLE_INSTANCE_REF — InstanceReference / InstanceReferenceEntity value does not resolve to a document instance id. List values (JSON ['id'] or repeated instance tags) are checked item-wise.
     • BML_TYPE_BOUND_NOT_SATISFIED — TypeReference(B) / TypeReferenceEntity(B) value fails bound B (capability throws[] defaults to core:Exception)
     TypeIdentifier / PackageIdentifier / InstanceIdentifier / MemberIdentifier (and *IdentifierEntity) values are not existence-checked. block.type is TypeIdentifier.
     • BML_MEMBER_COLLISION — duplicate member identity in effective set
-    • BML_OVERRIDE_WITHOUT_PARENT — override without resolvable base member
-    • BML_OVERRIDE_REQUIRED — override on non-overridable member
+    • BML_OVERRIDE_WITHOUT_PARENT — override="true" without a matching inherited or contract member
+    • BML_OVERRIDE_REQUIRED — local redeclaration of an inherited or contract member without override="true" (all member kinds, including aggregation composition fills)
     • BML_EXPRESSION_PARSE_ERROR — parseExpression failed on ExpressionValue.raw
     • BML_EXPR_SYNTAX_ERROR — unclosed ${} in interpolated text
     • BML_EXPR_NOT_ALLOWED_IN_INTERPOLATION — hole uses @model, @bean, or a forbidden call
     • BML_EXPR_TYPE_MISMATCH — interpolated text on a non-Text member
     • BML_INVALID_VALUE — PrimitiveType.parseValue threw on a canonical BML literal
       (property.value, values[namespace=""], instance memberValues, TypeReferenceEntity.value).
+      A JSON-like `[…]` payload without `[]` multiplicity is also this code
+      (collection on a non-list type), including on StructType. Struct values are
+      named field mappings, not positional arrays.
       Prefixed values (scad:value and other Annotation FQNs) are not validated today.
       TODO: a matching prefixed type (scad:type for scad:value) so each facet can be
       checked in its target language. Message is the thrown Error text. Expressions,
       interpolation, unions, StructType, and EnumType are skipped.
-
+    
     validateInstances:
     • BML_UNKNOWN_TYPE — composition instance typeFqn not in TypeRegistry
     • BML_UNKNOWN_PROPERTY — instance memberValues key not in effective members (error)
-
+    
     validateGenerics:
     • BML_OPEN_GENERIC_INSTANCE — aggregated domain Block instance still has open genericTypes without bml:generics (not TypeReferenceEntity sugar)
     • BML_GENERICS_DIRECTIVE_NOT_ALLOWED — bml:generics not on a Block instance (including TypeReferenceEntity QName sugar)
     • BML_GENERICS_ARGUMENT_MISMATCH — bml:generics does not match declared genericTypes (including on a non-generic type)
     • BML_MISSING_GENERIC_TYPE_ARGUMENT — directive present but a required argument has no defaultType
     • BML_GENERIC_CONSTRAINT_VIOLATION — argument fails parameter baseType via satisfiesTypeBound
-
+    
     validateVersions:
     • BML_MISSING_VERSION — standalone root block missing effective version (non-framework convention)
     • BML_UNKNOWN_VERSION — bml:version pin does not match registered block version
-
+    
     validateConstraints:
     • BML_CONSTRAINT_VIOLATION — constraint predicate failed
     • BML_CONSTRAINT_UNKNOWN — unrecognized constraint type FQN
     • BML_CONSTRAINT_TARGET_MISMATCH — constraint branch wrong for embed context
-
+    
     bootstrap:
     • BML_BOOTSTRAP_READ_ERROR — file read failure during corpus walk (warning)
     • BML_LIBRARY_RESOLVE_ERROR — Library.bml path or dependency could not be resolved
     • BML_LIBRARY_NESTING_VIOLATION — outer library re-exports inner-only block
-
-    Diagnostic type: org.blockml.bml.bom.common.Diagnostic.</documentation>
-
+    
+    Diagnostic type: org.blockml.bml.bom.common.Diagnostic.
+  </documentation>
   <references>
     <see type="fwconfig:FrameworkDiagnosticCodes" relation="Defines" />
     <see type="fwdocumentation:PackageOwnership" relation="ReadNext" />
   </references>
-
-</block>
+</fwdocumentation:Diagnostics>

package/blocks/org/blockml/bml/framework/documentation/EffectiveMembers.bml

@@ -1,12 +1,6 @@
-<!--
-  Framework Documentation — EffectiveMembers
-  FQN: org.blockml.bml.framework.documentation.EffectiveMembers
--->
-<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
-                      "
+<!--Framework Documentation — EffectiveMembers
+  FQN: org.blockml.bml.framework.documentation.EffectiveMembers-->
+<fwdocumentation:EffectiveMembers xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -32,35 +26,36 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>EffectiveMembers</name>
-  <type>fwdocumentation:EffectiveMembers</type>
-  <baseType>core:Documentation</baseType>
-  <is>resolveEffectiveMembers and baseType chain merge</is>
-
-  <documentation>resolveEffectiveMembers(block, registry) merges members[] in order:
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    resolveEffectiveMembers and baseType chain merge
+  </is>
+  <documentation>
+    resolveEffectiveMembers(block, registry) merges members[] in order:
+    
     1. baseType chain (via collectBaseTypeChain) — earliest to latest
     2. contracts[] in declaration order (via resolveContracts) — contract Block members only;
        subBlocks/compositions/embeddedBlocks on contract types are ignored
     3. local block.members — override earlier layers when override=true
-
+    
     collectBaseTypeChain walks block.baseType → registry.get(baseType) until absent or cycle.
     resolveContracts resolves each contracts[] FQN via TypeRegistry; unknown contract →
     BML_UNKNOWN_CONTRACT (validateTypes).
     memberIdentityKey(member) = (namespace ?? "") + ":" + name — collision detection key.
     findLocalMember(block, member) looks up that key in block.members only (not inherited).
-
+    
     Partial merge: later layer replaces only explicitly authored attributes on the member.
     Used by validateTypes (member collision, override rules) and validateConstraints (effective
     PropertyDefinition constraints).
-
-    EffectiveMemberSet is a runtime view — not stored on Urmodell (BOM SSOT).</documentation>
-
+    
+    EffectiveMemberSet is a runtime view — not stored on Urmodell (BOM SSOT).
+  </documentation>
   <references>
     <see type="fwdocumentation:ExpressionParsing" relation="ReadNext" />
     <see type="fwcap:ResolveEffectiveMembers" relation="Defines" />
     <see type="fwcap:ResolveContracts" relation="SeeAlso" />
     <see type="fwcap:FindLocalMember" relation="SeeAlso" />
   </references>
-
-</block>
+</fwdocumentation:EffectiveMembers>

package/blocks/org/blockml/bml/framework/documentation/ExpressionParsing.bml

@@ -1,12 +1,6 @@
-<!--
-  Framework Documentation — ExpressionParsing
-  FQN: org.blockml.bml.framework.documentation.ExpressionParsing
--->
-<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
-                      "
+<!--Framework Documentation — ExpressionParsing
+  FQN: org.blockml.bml.framework.documentation.ExpressionParsing-->
+<fwdocumentation:ExpressionParsing xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -32,28 +26,33 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>ExpressionParsing</name>
-  <type>fwdocumentation:ExpressionParsing</type>
-  <baseType>core:Documentation</baseType>
-  <is>parseExpression AST — no Urmodell writeback (B4)</is>
-
-  <documentation>parseExpression(source) parses expression text into an ExpressionNode AST.
-    parseInterpolatedText(source) scans Text for ${} holes (restricted profile).
-    Lookup is the same as full expressions: size ≡ #this.size, this ≡ #this.this.
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    parseExpression AST — no Urmodell writeback (B4)
+  </is>
+  <documentation>
+    parseExpression(source) parses expression text into an ExpressionNode AST.
+    parseInterpolatedText(source) scans Text for unescaped ${} holes (restricted
+    profile). `\${` is a literal `${`; `\\${` is one `\` plus a hole (odd/even
+    backslashes immediately before `$`). Lookup is the same as full expressions:
+    size ≡ #this.size, this ≡ #this.this.
     Returns ParseExpressionOutcome: { ok: true, result } | { ok: false, error }.
-
+    Empty expression text → BML_EXPRESSION_PARSE_ERROR (write `\${ }` for literal
+    delimiter characters).
+    
     Parser stores ExpressionValue.raw / InterpolatedTextValue.raw only (B4).
     validateTypes re-parses at validation time and emits BML_EXPRESSION_PARSE_ERROR
     or BML_EXPR_NOT_ALLOWED_IN_INTERPOLATION on failure.
-
+    
     AST node kinds: literal, array, object, property, call, binary, interpolated.
     Optional resultTypeFqn on ParseExpressionResult for typed expression metadata.
-
-    Expression AST is a Stage-2 utility — never written back to Urmodell member values.</documentation>
-
+    
+    Expression AST is a Stage-2 utility — never written back to Urmodell member values.
+  </documentation>
   <references>
     <see type="fwdocumentation:ConstraintValidation" relation="ReadNext" />
     <see type="fwexpression:ExpressionNode" relation="Defines" />
   </references>
-
-</block>
+</fwdocumentation:ExpressionParsing>

package/blocks/org/blockml/bml/framework/documentation/Introduction.bml

@@ -1,12 +1,6 @@
-<!--
-  Framework Documentation — Introduction
-  FQN: org.blockml.bml.framework.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
-                      "
+<!--Framework Documentation — Introduction
+  FQN: org.blockml.bml.framework.documentation.Introduction-->
+<fwdocumentation:Introduction xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -32,28 +26,29 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>Introduction</name>
-  <type>fwdocumentation:Introduction</type>
-  <baseType>core:Documentation</baseType>
-  <is>Purpose and scope of the Framework utilities package</is>
-
-  <documentation>The @blockml/framework package provides Stage-2 framework utilities: TypeRegistry,
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Purpose and scope of the Framework utilities package
+  </is>
+  <documentation>
+    The @blockml/framework package provides Stage-2 framework utilities: TypeRegistry,
     bootstrapTypeRegistry, forkBom, resolveEffectiveMembers, parseExpression, validateTypes,
     and validateConstraints.
-
+    
     This library (org.blockml.bml.framework.*) is the SSOT. TypeScript in
     packages/framework/src/ implements it. Parity tests in packages/framework/test/
     verify BML ↔ TS alignment.
-
+    
     Stage-2 placement: after parse (Stage 1) and before render/compile targets.
     Consumed by @blockml/validator (orchestrator) and @blockml/cli (bootstrap host).
-
+    
     Language BML corpus remains in npm @blockml/core (node_modules). Framework utilities
-    operate on BomDocument (Urmodell) from @blockml/bom — they do not redefine meta-model blocks.</documentation>
-
+    operate on BomDocument (Urmodell) from @blockml/bom — they do not redefine meta-model blocks.
+  </documentation>
   <references>
     <see type="fwdocumentation:LayerSeparation" relation="ReadNext" />
     <see type="bomdocumentation:Introduction" relation="SeeAlso" />
   </references>
-
-</block>
+</fwdocumentation:Introduction>

package/blocks/org/blockml/bml/framework/documentation/LayerSeparation.bml

@@ -1,12 +1,6 @@
-<!--
-  Framework Documentation — LayerSeparation
-  FQN: org.blockml.bml.framework.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
-                      "
+<!--Framework Documentation — LayerSeparation
+  FQN: org.blockml.bml.framework.documentation.LayerSeparation-->
+<fwdocumentation:LayerSeparation xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -32,31 +26,32 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>LayerSeparation</name>
-  <type>fwdocumentation:LayerSeparation</type>
-  <baseType>core:Documentation</baseType>
-  <is>Framework vs BOM vs parser vs validator vs core</is>
-
-  <documentation>Five layers relevant to framework utilities:
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Framework vs BOM vs parser vs validator vs core
+  </is>
+  <documentation>
+    Five layers relevant to framework utilities:
+    
     org.blockml.bml.bom.* (@blockml/bom) — Urmodell data structures (BomDocument, …).
     ValidateOptions, ValidateResult, TypeRegistryReader (B26) live here.
-
+    
     org.blockml.bml.framework.* (this package) — TypeRegistry, fork/resolve/validate utilities,
     parseExpression AST (Stage 2). Does not own validate() orchestration.
-
+    
     org.blockml.bml.compiler.parser.* (@blockml/parser) — BML → BomDocument (Stage 1).
     bootstrapTypeRegistry calls parse() on corpus files.
-
+    
     org.blockml.bml.compiler.validator.* (@blockml/validator) — validate() entry point;
     orchestrates framework utilities on a pragmatic fork.
-
+    
     org.blockml.bml.definition.* (@blockml/core) — BML meta-model corpus (npm).
-    Framework reads Definition types via TypeRegistry; does not duplicate grammar blocks.</documentation>
-
+    Framework reads Definition types via TypeRegistry; does not duplicate grammar blocks.
+  </documentation>
   <references>
     <see type="fwdocumentation:ArchitectureOverview" relation="ReadNext" />
     <see type="bomdocumentation:LayerSeparation" relation="SeeAlso" />
   </references>
-
-</block>
+</fwdocumentation:LayerSeparation>

package/blocks/org/blockml/bml/framework/documentation/PackageOwnership.bml

@@ -1,12 +1,6 @@
-<!--
-  Framework Documentation — PackageOwnership
-  FQN: org.blockml.bml.framework.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
-                      "
+<!--Framework Documentation — PackageOwnership
+  FQN: org.blockml.bml.framework.documentation.PackageOwnership-->
+<fwdocumentation:PackageOwnership xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -32,28 +26,29 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>PackageOwnership</name>
-  <type>fwdocumentation:PackageOwnership</type>
-  <baseType>core:Documentation</baseType>
-  <is>Toolchain package responsibilities for framework utilities</is>
-
-  <documentation>@blockml/framework — TypeRegistry, bootstrap, forkBom, resolveEffectiveMembers,
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Toolchain package responsibilities for framework utilities
+  </is>
+  <documentation>
+    @blockml/framework — TypeRegistry, bootstrap, forkBom, resolveEffectiveMembers,
     parseExpression, validateTypes, validateConstraints. Owns this BML library.
-
+    
     @blockml/bom — Urmodell types, ValidateOptions/ValidateResult, TypeRegistryReader,
     Diagnostic. Framework consumes; does not redefine.
-
+    
     @blockml/parser — parse() used during bootstrap only.
-
+    
     @blockml/validator — validate() orchestrator; calls framework utilities.
-
+    
     @blockml/core (npm) — language/meta-model BML corpus; bootstrap source.
-
-    @blockml/cli — TypeRegistry bootstrap host and validate/compile orchestration.</documentation>
-
+    
+    @blockml/cli — TypeRegistry bootstrap host and validate/compile orchestration.
+  </documentation>
   <references>
     <see type="fwdocumentation:ScopeExclusions" relation="ReadNext" />
     <see type="bomdocumentation:PackageOwnership" relation="SeeAlso" />
   </references>
-
-</block>
+</fwdocumentation:PackageOwnership>

package/blocks/org/blockml/bml/framework/documentation/PublicApi.bml

@@ -1,12 +1,6 @@
-<!--
-  Framework Documentation — PublicApi
-  FQN: org.blockml.bml.framework.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
-                      "
+<!--Framework Documentation — PublicApi
+  FQN: org.blockml.bml.framework.documentation.PublicApi-->
+<fwdocumentation:PublicApi xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -32,13 +26,16 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>PublicApi</name>
-  <type>fwdocumentation:PublicApi</type>
-  <baseType>core:Documentation</baseType>
-  <is>Framework public exports from index.ts</is>
-
-  <documentation><![CDATA[Public exports from @blockml/framework (packages/framework/src/index.ts):
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Framework public exports from index.ts
+  </is>
+  <documentation>
+    <![CDATA[
+    Public exports from @blockml/framework (packages/framework/src/index.ts):
+    
     TypeRegistry — class; register/get/has/keys/size/withOverlay on BomDocument index
     bootstrapTypeRegistry(options?) → BootstrapResult
     bootstrapFullProjectRegistry({ rootDir, srcDir?, libraries? }) → BootstrapResult
@@ -70,14 +67,14 @@
     validateConstraints(document, registry) → Diagnostic[]
     getPropertyNumericValue(property) → number | undefined
     isLiteralValue(value) → boolean
-
+    
     Types: BootstrapResult, BootstrapTrace, BootstrapOptions, ExpressionNode, ParseExpressionResult, ParseExpressionOutcome
-
-    Not exported from index: getLiteralNumericValue (internal helper in validate-types.ts).]]></documentation>
-
+    
+    Not exported from index: getLiteralNumericValue (internal helper in validate-types.ts).
+    ]]>
+  </documentation>
   <references>
     <see type="fwdocumentation:TypeRegistryBootstrap" relation="ReadNext" />
     <see type="bomapi:TypeRegistryReader" relation="SeeAlso" />
   </references>
-
-</block>
+</fwdocumentation:PublicApi>

package/blocks/org/blockml/bml/framework/documentation/ScopeExclusions.bml

@@ -1,12 +1,6 @@
-<!--
-  Framework Documentation — ScopeExclusions
-  FQN: org.blockml.bml.framework.documentation.ScopeExclusions
--->
-<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
-                      "
+<!--Framework Documentation — ScopeExclusions
+  FQN: org.blockml.bml.framework.documentation.ScopeExclusions-->
+<fwdocumentation:ScopeExclusions xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -32,24 +26,25 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>ScopeExclusions</name>
-  <type>fwdocumentation:ScopeExclusions</type>
-  <baseType>core:Documentation</baseType>
-  <is>Explicit out-of-scope for the framework package</is>
-
-  <documentation>Out of scope for @blockml/framework:
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Explicit out-of-scope for the framework package
+  </is>
+  <documentation>
+    Out of scope for @blockml/framework:
+    
     • parse() / serialize() public entry points — @blockml/parser / @blockml/serializer
     • validate() orchestration — @blockml/validator
     • CLI / file orchestration — @blockml/cli
     • Render target emit — @blockml/compiler / domain packages
     • Language BML block authorship — @blockml/core (npm)
     • BomBuilder (V3) — future; framework accepts its output types only
-
-    In scope: Stage-2 utilities on BomDocument with TypeRegistry-backed semantic checks.</documentation>
-
+    
+    In scope: Stage-2 utilities on BomDocument with TypeRegistry-backed semantic checks.
+  </documentation>
   <references>
     <see type="fwdocumentation:Introduction" relation="SeeAlso" />
   </references>
-
-</block>
+</fwdocumentation:ScopeExclusions>

package/blocks/org/blockml/bml/framework/documentation/TypeRegistryBootstrap.bml

@@ -1,12 +1,6 @@
-<!--
-  Framework Documentation — TypeRegistryBootstrap
-  FQN: org.blockml.bml.framework.documentation.TypeRegistryBootstrap
--->
-<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
-                      "
+<!--Framework Documentation — TypeRegistryBootstrap
+  FQN: org.blockml.bml.framework.documentation.TypeRegistryBootstrap-->
+<fwdocumentation:TypeRegistryBootstrap xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -32,16 +26,18 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>TypeRegistryBootstrap</name>
-  <type>fwdocumentation:TypeRegistryBootstrap</type>
-  <baseType>core:Documentation</baseType>
-  <is>defaultBootstrapPaths and bootstrapTypeRegistry</is>
-
-  <documentation>bootstrapTypeRegistry(options?) supports two modes:
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    defaultBootstrapPaths and bootstrapTypeRegistry
+  </is>
+  <documentation>
+    bootstrapTypeRegistry(options?) supports two modes:
+    
     corpus (default) — walks options.paths (or defaultBootstrapPaths()) for all .bml files,
     parses via @blockml/parser parse(), registers each document root block.
-
+    
     library — when options.libraryPaths is set, resolves each Library.bml dependency graph
     (dependencies, subLibraries) in order, then registers blocks from each library blocks root
     except trees already covered by options.paths (srcDir / corpus). Missing Library path →
@@ -50,43 +46,42 @@
     BML_LIBRARY_NESTING_VIOLATION. Duplicate files of the same type FQN are resolved by
     source priority: a path not under node_modules (workspace / project sources) wins over
     an npm copy; same-origin last write wins. The losing file is not compared and is not kept.
-
+    
     defaultBootstrapPaths(rootDir?) returns BlockML srcDir roots for production
     npm dependencies (package.json dependencies + optionalDependencies) of the nearest
     package, resolved via node_modules walk-up. Used as corpus fallback when no paths
     are given. A BlockML package is identified by blockml.library or blockml.config.json;
     its source root is srcDir (default "blocks", override only in that package's
     blockml.config.json).
-
+    
     resolveLibrarySeeds(rootDir, extras?) prepends package.json blockml.library, then
     extras (config.libraries / --libraries), deduped by realpath.
-
+    
     bootstrapFullProjectRegistry({ rootDir, srcDir?, libraries? }) is the shared
     entry point for `blockml validate --all`, `@blockml/search`, and `@blockml/graph`. It sets
     corpus paths to projectSourceRoots (this package srcDir plus local packages/*
     BlockML modules) and library seeds to resolveLibrarySeeds, then calls
     bootstrapTypeRegistry. The resulting registry is the effective BML corpus:
     local project files plus the library graph including npm BlockML packages.
-
+    
     bootstrapTypeRegistry also indexes Library.bml under all BlockML packages found in
     workspace packages/ and node_modules along the directory walk (FQN search space).
     Local srcDir and workspace packages are indexed before node_modules.
     resolveDepCandidate / findLibraryFileForType pick workspace over npm when the same
     Library type FQN exists in both (Core dogfooding against an installed copy).
-
+    
     BootstrapResult: { registry, diagnostics, exportsByLibrary?, trace? }
     trace lists corpusPaths, seeds, searchRoots (index only), librariesVisited, and
     skippedCoveredRoots. Read errors emit BML_BOOTSTRAP_READ_ERROR (warning). Parse
     diagnostics are collected but do not stop registration of successfully parsed
     documents.
-
+    
     Hosts (@blockml/cli, @blockml/validator) may inject a pre-built TypeRegistry via
     ValidateOptions.typeRegistry instead of bootstrapping. ValidateOptions.libraryPaths
-    selects library mode when typeRegistry is omitted.</documentation>
-
+    selects library mode when typeRegistry is omitted.
+  </documentation>
   <references>
     <see type="fwdocumentation:EffectiveMembers" relation="ReadNext" />
     <see type="fwcap:BootstrapTypeRegistry" relation="Defines" />
   </references>
-
-</block>
+</fwdocumentation:TypeRegistryBootstrap>