@blockml/framework 0.9.0 → 0.9.2

package/blocks/org/blockml/bml/framework/Library.bml

@@ -49,7 +49,7 @@
     Membership is defined exclusively by this blocks list.
   </documentation>
 
-  <version>0.9.0</version>
+  <version>0.9.2</version>
 
   <language>
     <English />
@@ -87,6 +87,7 @@
         <fwexpression:PropertyExpressionNode />
         <fwexpression:CallExpressionNode />
         <fwexpression:BinaryExpressionNode />
+        <fwexpression:InterpolatedStringNode />
         <fwexpression:ParseExpressionResult />
         <fwexpression:ParseExpressionError />
         <fwexpression:ParseExpressionOutcome />
@@ -106,7 +107,11 @@
         <fwcap:ResolveEffectiveMembers />
         <fwcap:CollectBaseTypeChain />
         <fwcap:MemberIdentityKey />
+        <fwcap:FindLocalMember />
         <fwcap:ParseExpression />
+        <fwcap:ParseInterpolatedText />
+        <fwcap:EvaluateExpression />
+        <fwcap:EvaluateInterpolatedText />
         <fwcap:ValidateTypes />
         <fwcap:ValidateConstraints />
         <fwcap:ValidateVersions />
@@ -116,11 +121,13 @@
         <fwcap:PeekLibraryTypeFqn />
         <fwcap:ValidateEmbeddedBlocks />
         <fwcap:ValidateInstances />
+        <fwcap:ValidateGenerics />
         <fwcap:ValidatePresets />
         <fwcap:ValidateVisibility />
         <fwcap:ValidateReadOnly />
         <fwcap:GetPropertyNumericValue />
         <fwcap:IsLiteralValue />
+        <fwcap:EvaluateParseValue />
         <fwdocumentation:Introduction />
         <fwdocumentation:LayerSeparation />
         <fwdocumentation:ArchitectureOverview />

package/blocks/org/blockml/bml/framework/capability/EvaluateExpression.bml

@@ -0,0 +1,50 @@
+<!--
+  Framework Capability — EvaluateExpression
+  FQN: org.blockml.bml.framework.capability.EvaluateExpression
+-->
+<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:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:fwconfig="org.blockml.bml.framework.config"
+  xmlns:fwdocumentation="org.blockml.bml.framework.documentation"
+  xmlns:fwexpression="org.blockml.bml.framework.expression"
+  xmlns:fwregistry="org.blockml.bml.framework.registry"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
+
+  <name>EvaluateExpression</name>
+  <type>fwcap:EvaluateExpression</type>
+  <baseType>core:Capability</baseType>
+  <is>Evaluate a restricted expression AST against the #this scope</is>
+
+  <documentation>#this is the outer Block property map. Same lookup as full expressions: size ≡ #this.size, this ≡ #this.this, this.x ≡ #this.this.x. Restricted profile only.</documentation>
+
+  <properties>
+    <node type="fwexpression:ExpressionNode">
+      <documentation>node. TS type: fwexpression:ExpressionNode. (required)</documentation>
+    </node>
+    <value type="type:Text">
+      <documentation>BML type gap: TS unknown evaluation result. (required)</documentation>
+    </value>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/framework/capability/EvaluateInterpolatedText.bml

@@ -0,0 +1,50 @@
+<!--
+  Framework Capability — EvaluateInterpolatedText
+  FQN: org.blockml.bml.framework.capability.EvaluateInterpolatedText
+-->
+<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:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:fwconfig="org.blockml.bml.framework.config"
+  xmlns:fwdocumentation="org.blockml.bml.framework.documentation"
+  xmlns:fwexpression="org.blockml.bml.framework.expression"
+  xmlns:fwregistry="org.blockml.bml.framework.registry"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
+
+  <name>EvaluateInterpolatedText</name>
+  <type>fwcap:EvaluateInterpolatedText</type>
+  <baseType>core:Capability</baseType>
+  <is>Evaluate interpolated text against the #this scope</is>
+
+  <documentation>Parses holes then evaluates them with the same #this lookup as full expressions. Result is concatenated Text.</documentation>
+
+  <properties>
+    <source type="type:Text">
+      <documentation>source. TS type: type:Text. (required)</documentation>
+    </source>
+    <value type="type:Text">
+      <documentation>value. TS type: type:Text. (required)</documentation>
+    </value>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/framework/capability/EvaluateParseValue.bml

@@ -0,0 +1,68 @@
+<!--
+  Framework Capability — EvaluateParseValue
+  FQN: org.blockml.bml.framework.capability.EvaluateParseValue
+-->
+<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:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:fwconfig="org.blockml.bml.framework.config"
+  xmlns:fwdocumentation="org.blockml.bml.framework.documentation"
+  xmlns:fwexpression="org.blockml.bml.framework.expression"
+  xmlns:fwregistry="org.blockml.bml.framework.registry"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
+
+  <name>EvaluateParseValue</name>
+  <type>fwcap:EvaluateParseValue</type>
+  <baseType>core:Capability</baseType>
+  <is>Evaluate PrimitiveType.parseValue on authored text</is>
+
+  <documentation>
+    Host-evaluable PrimitiveType.parseValue: Text → host value.
+
+    - Looks up `parseValue` on the named primitive (multiplicity and generics stripped)
+    - No member, abstract, non-TypeScript, or type missing from the registry → skipped
+    - A thrown Error → `BML_INVALID_VALUE`
+    - Lexical only — no `this.min` / `this.max`, no TypeRegistry existence
+  </documentation>
+
+  <references>
+    <see type="fwcap:ResolveEffectiveMembers" relation="SeeAlso" />
+    <see type="fwcap:ValidateTypes" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <typeFqn type="type:Text">
+      <documentation>Declared primitive FQN or type expression. (required)</documentation>
+    </typeFqn>
+    <raw type="type:Text">
+      <documentation>Authored XML text. (required)</documentation>
+    </raw>
+    <registry type="fwcap:TypeRegistry">
+      <documentation>registry. TS type: fwcap:TypeRegistry. (required)</documentation>
+    </registry>
+    <result type="type:Text">
+      <documentation>ok+value, ok+skipped, or ok:false+message. (required)</documentation>
+    </result>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/framework/capability/FindLocalMember.bml

@@ -0,0 +1,58 @@
+<!--
+  Framework Capability — FindLocalMember
+  FQN: org.blockml.bml.framework.capability.FindLocalMember
+-->
+<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:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:fwconfig="org.blockml.bml.framework.config"
+  xmlns:fwdocumentation="org.blockml.bml.framework.documentation"
+  xmlns:fwexpression="org.blockml.bml.framework.expression"
+  xmlns:fwregistry="org.blockml.bml.framework.registry"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
+
+  <name>FindLocalMember</name>
+  <type>fwcap:FindLocalMember</type>
+  <baseType>core:Capability</baseType>
+  <is>Find a member declared on this block, not inherited</is>
+
+  <documentation>Looks up memberIdentityKey(member) in block.members only. Returns the local declaration, or undefined when the member is inherited or absent.</documentation>
+
+  <references>
+    <see type="fwcap:MemberIdentityKey" relation="SeeAlso" />
+    <see type="fwcap:ResolveEffectiveMembers" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <block type="bomblock:BlockDefinition">
+      <documentation>block. TS type: bomblock:BlockDefinition. (required)</documentation>
+    </block>
+    <member type="bommember:MemberDefinition">
+      <documentation>member. TS type: bommember:MemberDefinition. (required)</documentation>
+    </member>
+    <local type="bommember:MemberDefinition">
+      <documentation>Declared member on this block, or undefined. (optional)</documentation>
+    </local>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/framework/capability/ForkBom.bml

@@ -39,7 +39,7 @@
   <documentation>Deep-clone Urmodell for pragmatic / validation working copy</documentation>
 
   <references>
-    <see type="bomdocumentation:PragmaticModel" relation="SeeAlso" />
+    <see type="bomdocumentation:PublicApi" relation="SeeAlso" />
   </references>
 
   <properties>

package/blocks/org/blockml/bml/framework/capability/ParseInterpolatedText.bml

@@ -0,0 +1,54 @@
+<!--
+  Framework Capability — ParseInterpolatedText
+  FQN: org.blockml.bml.framework.capability.ParseInterpolatedText
+-->
+<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:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:fwconfig="org.blockml.bml.framework.config"
+  xmlns:fwdocumentation="org.blockml.bml.framework.documentation"
+  xmlns:fwexpression="org.blockml.bml.framework.expression"
+  xmlns:fwregistry="org.blockml.bml.framework.registry"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
+
+  <name>ParseInterpolatedText</name>
+  <type>fwcap:ParseInterpolatedText</type>
+  <baseType>core:Capability</baseType>
+  <is>Parse interpolated text into an InterpolatedStringNode AST</is>
+
+  <documentation>Scan authored text for ${} holes. Restricted profile — same #this lookup as full expressions; no @model, @bean, or capability calls.</documentation>
+
+  <references>
+    <see type="fwdocumentation:ExpressionParsing" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <source type="type:Text">
+      <documentation>source. TS type: type:Text. (required)</documentation>
+    </source>
+    <outcome type="fwexpression:ParseExpressionOutcome">
+      <documentation>outcome. TS type: fwexpression:ParseExpressionOutcome. (required)</documentation>
+    </outcome>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/framework/capability/TypeRegistry.bml

@@ -36,7 +36,16 @@
   <baseType>core:Capability</baseType>
   <is>In-memory index of BlockDefinition documents by type FQN</is>
 
-  <documentation>Class exported from registry/type-registry.ts. Implements bomapi:TypeRegistryReader (get/has).</documentation>
+  <documentation>
+    # In-memory index of BlockDefinition documents by type FQN
+
+    Class exported from registry/type-registry.ts. Implements bomapi:TypeRegistryReader (get/has).
+
+    - register prefers a non-node_modules source over a node_modules source for the same type FQN
+      (workspace beats dependency). Same-origin last write wins.
+    - withOverlay(document) returns a copy with that document registered — open-buffer overlay;
+      does not mutate this registry.
+  </documentation>
 
   <references>
     <see type="bomapi:TypeRegistryReader" relation="SeeAlso" />

package/blocks/org/blockml/bml/framework/capability/ValidateGenerics.bml

@@ -0,0 +1,66 @@
+<!--
+  Framework Capability — ValidateGenerics
+  FQN: org.blockml.bml.framework.capability.ValidateGenerics
+-->
+<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:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:fwconfig="org.blockml.bml.framework.config"
+  xmlns:fwdocumentation="org.blockml.bml.framework.documentation"
+  xmlns:fwexpression="org.blockml.bml.framework.expression"
+  xmlns:fwregistry="org.blockml.bml.framework.registry"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:pardocumentation="org.blockml.bml.compiler.parser.documentation"
+  xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
+
+  <name>ValidateGenerics</name>
+  <type>fwcap:ValidateGenerics</type>
+  <baseType>core:Capability</baseType>
+  <is>Open generic instance and bml:generics placement checks</is>
+
+  <documentation>Open generic instance and bml:generics placement checks against
+    TypeRegistry. Emits BML_OPEN_GENERIC_INSTANCE, BML_GENERICS_DIRECTIVE_NOT_ALLOWED,
+    BML_GENERICS_ARGUMENT_MISMATCH, and reuses BML_GENERIC_CONSTRAINT_VIOLATION /
+    BML_MISSING_GENERIC_TYPE_ARGUMENT.
+
+    bml:generics is allowed whenever the instance type declares genericTypes.
+    Open parameters require a binding. Parameters with defaultType may omit it;
+    authored arguments override defaultType.
+
+    BML_OPEN_GENERIC_INSTANCE applies only to domain Block instances. Children of a
+    TypeReferenceEntity aggregation (Library blocks, contracts, …) are type
+    references — empty QName sugar or explicit TypeReferenceEntity — not instances
+    of the named type. They must not carry bml:generics; if present, emit
+    BML_GENERICS_DIRECTIVE_NOT_ALLOWED.</documentation>
+
+  <properties>
+    <document type="bomdoc:BomDocument">
+      <documentation>document. TS type: bomdoc:BomDocument. (required)</documentation>
+    </document>
+    <registry type="fwcap:TypeRegistry">
+      <documentation>registry. TS type: fwcap:TypeRegistry. (required)</documentation>
+    </registry>
+    <diagnostics type="bomcommon:Diagnostic[]">
+      <documentation>diagnostics. TS type: bomcommon:Diagnostic[]. (required)</documentation>
+    </diagnostics>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/framework/capability/ValidateTypes.bml

@@ -36,11 +36,29 @@
   <baseType>core:Capability</baseType>
   <is>Semantic type checks on BomDocument using TypeRegistry</is>
 
-  <documentation>Semantic type checks on BomDocument using TypeRegistry</documentation>
+  <documentation>
+    Semantic type checks on BomDocument using TypeRegistry.
+
+    Existence is classified per declared ValueType — there is no shared MemberReference parent:
+
+    - TypeReference, PackageReference, InstanceReference, PropertyReference, AggregationReference,
+      AssociationReference, CapabilityReference, and the matching *ReferenceEntity wrappers
+    - Identifier types (`TypeIdentifier`, `MemberIdentifier`, …) are syntax-only and are not
+      existence-checked
+
+    After the reference walk, canonical BML literals with a declared PrimitiveType are
+    checked via fwcap:EvaluateParseValue (property.value / values[namespace=""]).
+    Prefixed / annotation-namespaced PropertyValueEntry values (scad:value and other
+    Annotation FQNs) are not validated today — they are target-language facets, not
+    BML lexical values. TODO: a matching prefixed type (for example scad:type for
+    scad:value) so each facet can be parseValue-checked in its own language.
+    Failure → BML_INVALID_VALUE. Existence stays on the reference walk.
+  </documentation>
 
   <references>
     <see type="fwcap:ResolveEffectiveMembers" relation="SeeAlso" />
     <see type="fwcap:ParseExpression" relation="SeeAlso" />
+    <see type="fwcap:EvaluateParseValue" relation="SeeAlso" />
   </references>
 
   <properties>

package/blocks/org/blockml/bml/framework/config/FrameworkDiagnosticCodes.bml

@@ -40,7 +40,7 @@
 
   <properties>
     <codes type="type:Text[]">
-      <documentation>Ordered: BML_BOOTSTRAP_READ_ERROR, BML_CONSTRAINT_INFORMATION, BML_CONSTRAINT_TARGET_MISMATCH, BML_CONSTRAINT_UNKNOWN, BML_CONSTRAINT_VIOLATION, BML_CONSTRAINT_WARNING, BML_DUPLICATE_EMBEDDED_BLOCK, BML_DUPLICATE_MEMBER_VISIBILITY_VARIANT, BML_EMBEDDED_BLOCKS_ON_SUBBLOCK, BML_EXPRESSION_PARSE_ERROR, BML_LIBRARY_NESTING_VIOLATION, BML_LIBRARY_RESOLVE_ERROR, BML_MEMBER_COLLISION, BML_MISSING_ID, BML_MISSING_VERSION, BML_NESTED_EMBEDDED_BLOCKS, BML_OVERRIDE_REQUIRED, BML_OVERRIDE_WITHOUT_PARENT, BML_PRESET_CYCLE, BML_READONLY_MEMBER_WRITE, BML_SUBBLOCK_TYPE_MISMATCH, BML_TYPE_BOUND_NOT_SATISFIED, BML_UNRESOLVABLE_INSTANCE_REF, BML_UNKNOWN_BASE_TYPE, BML_UNKNOWN_CONTRACT, BML_UNKNOWN_TYPE, BML_UNKNOWN_PROPERTY, BML_UNKNOWN_VERSION, BML_VISIBILITY_PRIVATE_OVERRIDE (required)</documentation>
+      <documentation>Ordered: BML_BOOTSTRAP_READ_ERROR, BML_CONSTRAINT_INFORMATION, BML_CONSTRAINT_TARGET_MISMATCH, BML_CONSTRAINT_UNKNOWN, BML_CONSTRAINT_VIOLATION, BML_CONSTRAINT_WARNING, BML_DUPLICATE_EMBEDDED_BLOCK, BML_DUPLICATE_MEMBER_VISIBILITY_VARIANT, BML_EMBEDDED_BLOCKS_ON_SUBBLOCK, BML_EXPRESSION_PARSE_ERROR, BML_EXPR_NOT_ALLOWED_IN_INTERPOLATION, BML_EXPR_SYNTAX_ERROR, BML_EXPR_TYPE_MISMATCH, BML_GENERIC_CONSTRAINT_VIOLATION, BML_GENERICS_ARGUMENT_MISMATCH, BML_GENERICS_DIRECTIVE_NOT_ALLOWED, BML_INVALID_VALUE, BML_LIBRARY_NESTING_VIOLATION, BML_LIBRARY_RESOLVE_ERROR, BML_MEMBER_COLLISION, BML_MISSING_GENERIC_TYPE_ARGUMENT, BML_MISSING_ID, BML_MISSING_VERSION, BML_NESTED_EMBEDDED_BLOCKS, BML_OPEN_GENERIC_INSTANCE, BML_OVERRIDE_REQUIRED, BML_OVERRIDE_WITHOUT_PARENT, BML_PRESET_CYCLE, BML_READONLY_MEMBER_WRITE, BML_SUBBLOCK_TYPE_MISMATCH, BML_TYPE_BOUND_NOT_SATISFIED, BML_UNRESOLVABLE_INSTANCE_REF, BML_UNKNOWN_BASE_TYPE, BML_UNKNOWN_CONTRACT, BML_UNKNOWN_TYPE, BML_UNKNOWN_PROPERTY, BML_UNKNOWN_VERSION, BML_VISIBILITY_PRIVATE_OVERRIDE (required)</documentation>
     </codes>
   </properties>
 

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

@@ -39,20 +39,39 @@
 
   <documentation>Diagnostic codes emitted by framework utilities (see fwconfig:FrameworkDiagnosticCodes):
 
-    validateTypes:
+    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 — named type FQN not in TypeRegistry and not a well-known primitive (member types at typeSource; instance typeFqn on the instance)
-    • BML_TYPE_BOUND_NOT_SATISFIED — capability throws[] type is not core:Exception (baseType chain or direct contracts[])
+    • 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
+    • 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_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_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).
+      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

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

@@ -48,6 +48,7 @@
     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
@@ -59,6 +60,7 @@
     <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>

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

@@ -38,12 +38,15 @@
   <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.
     Returns ParseExpressionOutcome: { ok: true, result } | { ok: false, error }.
 
-    Parser stores ExpressionValue.raw only (B4). validateTypes re-parses expressions
-    at validation time and emits BML_EXPRESSION_PARSE_ERROR on failure.
+    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.
+    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>

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

@@ -39,7 +39,7 @@
 
   <documentation><![CDATA[Public exports from @blockml/framework (packages/framework/src/index.ts):
 
-    TypeRegistry — class; register/get/has/keys/size on BomDocument index
+    TypeRegistry — class; register/get/has/keys/size/withOverlay on BomDocument index
     bootstrapTypeRegistry(options?) → BootstrapResult
     bootstrapFullProjectRegistry({ rootDir, srcDir?, libraries? }) → BootstrapResult
     defaultBootstrapPaths(rootDir?) → string[]
@@ -58,9 +58,15 @@
     resolveContracts(block, registry) → MemberDefinition[] (contract slice; used by resolveEffectiveMembers)
     collectBaseTypeChain(block, registry) → BlockDefinition[]
     memberIdentityKey(member) → string
+    findLocalMember(block, member) → MemberDefinition | undefined
     parseExpression(source) → ParseExpressionOutcome
+    parseInterpolatedText(source) → ParseExpressionOutcome
+    evaluateExpression(node, scope) → value
+    evaluateInterpolatedText(source, scope) → Text
     validateTypes(document, registry) → Diagnostic[]
     validateVersions(document, registry) → Diagnostic[]
+    validateInstances(document, registry) → Diagnostic[]
+    validateGenerics(document, registry) → Diagnostic[]
     validateConstraints(document, registry) → Diagnostic[]
     getPropertyNumericValue(property) → number | undefined
     isLiteralValue(value) → boolean

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

@@ -47,8 +47,9 @@
     except trees already covered by options.paths (srcDir / corpus). Missing Library path →
     BML_LIBRARY_RESOLVE_ERROR. Outer re-export of a block listed in a nested inner library's
     blocks (via subLibraries, including transitive nested inners) →
-    BML_LIBRARY_NESTING_VIOLATION. Duplicate files of the same library type FQN are not
-    compared and are not loaded.
+    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
@@ -61,17 +62,17 @@
     extras (config.libraries / --libraries), deduped by realpath.
 
     bootstrapFullProjectRegistry({ rootDir, srcDir?, libraries? }) is the shared
-    entry point for `blockml validate --all` and `@blockml/search`. It sets
+    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
-    node_modules and workspace packages/ along the directory walk (FQN search space).
-    First visited Library.bml wins per type FQN; a second file with the same type is not
-    loaded (workspace Core vs an installed copy). node_modules is indexed before
-    workspace packages.
+    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

package/blocks/org/blockml/bml/framework/expression/ExpressionNode.bml

@@ -36,7 +36,7 @@
   <baseType>framework:FrameworkType</baseType>
   <is>Abstract union of expression AST node variants</is>
 
-  <documentation>Discriminated by kind: literal | array | object | property | call | binary.</documentation>
+  <documentation>Discriminated by kind: literal | array | object | property | call | binary | interpolated.</documentation>
 
   <references>
     <see type="fwexpression:LiteralExpressionNode" relation="SeeAlso" />