@blockml/bom 0.1.0

package/blocks/org/blockml/bml/bom/documentation/DesignDecisions.bml

@@ -0,0 +1,64 @@
+<!--
+  BOM Documentation — DesignDecisions
+  FQN: org.blockml.bml.bom.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:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>DesignDecisions</name>
+  <type>bomdocumentation:DesignDecisions</type>
+  <baseType>core:Documentation</baseType>
+  <is>Normative Urmodell design decisions</is>
+
+  <documentation>Immutability: Urmodell (BomDocument) is immutable after parse or BomBuilder.seal().
+    No utility or renderer writes derived data back. Validator/renderers use pragmatic forks.
+
+    Builder / LSP reuse: construction-friendly, provenance-agnostic interfaces. Parser and
+    BomBuilder produce the same graph. Source spans optional on types but populated by parser.
+
+    Member inheritance: utility lookup only. BOM stores declared members per block.
+    resolveEffectiveMembers() → EffectiveMemberSet — never flattened into BOM.
+
+    Capabilities: stored in BOM; no synthetic getter/setter generation; renderer interprets.
+
+    Member identity: uniqueness by resolved (namespace, name).
+
+    Composition: nested inside aggregation on definitions only; instances open aggregations directly.
+
+    Sub-Blocks: nested in BlockDefinition.subBlocks[]; FQN = parent.type + "." + name.
+
+    Embedded Blocks: root embeddedBlocks[] only — virtual .bml files; FQN = type element.
+
+    Directives: flow-control bml:* → directives[] unexpanded. bml:id/version → BlockInstance fields.
+    bml:xml → first-class xmlRendering (not directives[]).
+
+    XML comments (B11): bind to following element; trailing on next line + blank line (B22).
+    Whitespace (B13): not on Urmodell. Dual placement (D9): store authoredPlacement.
+    Visibility (B14): logical name in BOM; emit _/__ from visibility.
+
+    Instance version: bml:version optional exact assert on external refs (BML_UNKNOWN_VERSION).
+    Definition version: effectiveBlockVersion = own version | library.version | error.
+    Instance id: bml:id only on BlockInstance.id; no auto-ID in BomDocument; bml:each requires id.
+
+    Property values: deep copy only — never linked. FQN::id cross-instance refs only on associations.</documentation>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/InstanceIdRules.bml

@@ -0,0 +1,45 @@
+<!--
+  BOM Documentation — InstanceIdRules
+  FQN: org.blockml.bml.bom.documentation.InstanceIdRules
+-->
+<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:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>InstanceIdRules</name>
+  <type>bomdocumentation:InstanceIdRules</type>
+  <baseType>core:Documentation</baseType>
+  <is>bml:id identity and cross-instance references</is>
+
+  <documentation>bml:id identifies child within parent composition tree. No FQN fallback.
+
+    Pipeline: Parse stores authored id → Validate cross-refs → Expand directives →
+    Resolve/auto-ID static unreferenced children → Render.
+
+    Auto-IDs NOT in BomDocument — only on expanded composition tree.
+    Referenced instances and bml:each require explicit bml:id (BML_MISSING_ID).
+
+    Auto-ID: hash(typeFqn, sibling index post-expansion, parent partId) → 6 hex chars.
+
+    Qualified FQN::id: target in public aggregation, literal id, literal reference token.
+    Same-document unqualified ids resolve within visible aggregations.</documentation>
+
+</block>

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

@@ -0,0 +1,50 @@
+<!--
+  BOM Documentation — Introduction
+  FQN: org.blockml.bml.bom.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:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>Introduction</name>
+  <type>bomdocumentation:Introduction</type>
+  <baseType>core:Documentation</baseType>
+  <is>Purpose and scope of the BOM Urmodell package</is>
+
+  <documentation>The @blockml/bom package defines the formal Block Object Model (Urmodell) — canonical,
+    immutable, lossless parse/build results produced by @blockml/parser (or V3 BomBuilder.seal())
+    and consumed by serializer, validator, compiler, LSP, and render targets.
+
+    This library (org.blockml.bml.bom.*) is the SSOT. TypeScript in packages/bom/src/ implements
+    it. Parity tests in packages/bom/test/ verify BML ↔ TS alignment.
+
+    Related reading outside this package:
+    • Conceptual foundations — 01_bom_core.md
+    • BML authoring syntax — org.blockml.bml.documentation.* (@blockml/core)
+    • BML → BOM mapping — @blockml/parser (13_bml_to_bom_mapping.md)
+    • Expression AST — 10_expression_language.md</documentation>
+
+  <references>
+    <see type="bomdocumentation:LayerSeparation" relation="ReadNext"></see>
+    <see type="bomdocumentation:ArchitectureOverview" relation="SeeAlso"></see>
+  </references>
+
+</block>

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

@@ -0,0 +1,47 @@
+<!--
+  BOM Documentation — LayerSeparation
+  FQN: org.blockml.bml.bom.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:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>LayerSeparation</name>
+  <type>bomdocumentation:LayerSeparation</type>
+  <baseType>core:Documentation</baseType>
+  <is>Urmodell types vs BML definition meta-model</is>
+
+  <documentation>Two layers share names but differ in semantics:
+
+    org.blockml.bml.definition.* (@blockml/core) — BML meta-model. Describes what block
+    definition documents mean (PropertyDefinition, BlockDefinition meta-type, …).
+
+    org.blockml.bml.bom.* (this package) — Urmodell runtime. Parse-result data structures
+    (BomDocument, BlockDefinition as TS interface, MemberDefinition, …).
+
+    Example: org.blockml.bml.definition.BlockDefinition describes BML syntax; org.blockml.bml.bom.block.BlockDefinition
+    describes the parser output shape. See 19_definition_blocks_and_bml_xml.md.</documentation>
+
+  <references>
+    <see type="def:BlockDefinition" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/MemberValueSemantics.bml

@@ -0,0 +1,48 @@
+<!--
+  BOM Documentation — MemberValueSemantics
+  FQN: org.blockml.bml.bom.documentation.MemberValueSemantics
+-->
+<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:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>MemberValueSemantics</name>
+  <type>bomdocumentation:MemberValueSemantics</type>
+  <baseType>core:Documentation</baseType>
+  <is>Property value deep-copy rules</is>
+
+  <documentation>Property values are never linked — always deep copies on instances and definitions.
+    Cross-instance FQN::id references exist only on associations (basePresets, Step.part, …).
+
+    EnumType tokens (Standard, FQN::id) are resolution keys — BOM stores id + typeFqn only.
+    Struct/primitive literals stay inline in authored form — not normalized at parse time.
+
+    LiteralValue: kind literal, opaque value, typeFqn, optional authoredPlacement (D9).
+    ExpressionValue: kind expression, raw ${} text only in BOM; AST via parseExpression().
+    AddressValue: parsed org.blockml.bml.type.Address shape.
+
+    Preset/config merge copies into render-time view — never writes references back to BomDocument.</documentation>
+
+  <references>
+    <see type="bomvalue:MemberValue" relation="Defines"></see>
+  </references>
+
+</block>

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

@@ -0,0 +1,56 @@
+<!--
+  BOM Documentation — PackageOwnership
+  FQN: org.blockml.bml.bom.documentation.PackageOwnership
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>PackageOwnership</name>
+  <type>bomdocumentation:PackageOwnership</type>
+  <baseType>core:Documentation</baseType>
+  <is>Toolchain package responsibilities for the Urmodell</is>
+
+  <documentation>@blockml/bom — all Urmodell interfaces, ParseResult/SerializeResult/ValidateResult (B26 + Stage 2),
+    ValidateOptions, TypeRegistryReader, Diagnostic (compiler result type), bomEquals/stripProvenance (B20),
+    future BomBuilder (V3).
+
+    @blockml/framework — TypeRegistry, forkBom, resolveEffectiveMembers, validateTypes, parseExpression.
+    Utilities never mutate Urmodell.
+
+    @blockml/core — BlockML language BML corpus (org.blockml.bml.*); npm SSOT in node_modules.
+
+    @blockml/parser — BML → BomDocument mapper; single file per invocation; parse() → ParseResult.
+    Does not own BOM interfaces or expand directives.
+
+    @blockml/serializer — BomDocument → canonical BML XML; serialize() → SerializeResult.
+
+    @blockml/validator — checks on BomDocument using framework utilities.
+
+    @blockml/cli — TypeRegistry bootstrap, validateTypes/validateConstraints, compile pipeline.
+
+    @blockml/lsp (V2) — reuses parser, validator, serializer; no parallel IDE AST.
+
+    @blockml/compiler — Target Registry facade.
+
+    @machineblocks/core — domain BML; extends TypeRegistry bootstrap.</documentation>
+
+</block>

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

@@ -0,0 +1,59 @@
+<!--
+  BOM Documentation — PublicApi
+  FQN: org.blockml.bml.bom.documentation.PublicApi
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>PublicApi</name>
+  <type>bomdocumentation:PublicApi</type>
+  <baseType>core:Documentation</baseType>
+  <is>Shared parse/serialize/validate results (B26 + Stage 2)</is>
+
+  <documentation>ParseResult: document (BomDocument | null), diagnostics[], success (false if any error).
+
+    SerializeResult: text (string | null), diagnostics[], success.
+
+    ValidateResult: optional pragmaticModel (forked BomDocument), diagnostics[], success.
+
+    ParseOptions: filePath (default "<memory>"), continueOnError (default true).
+
+    SerializeOptions: indent (default 2; 0=compact B13), xmlDeclaration (default false B17/B24).
+
+    ValidateOptions: typeRegistry (TypeRegistryReader), bootstrapPaths, libraryPaths,
+    continueOnError (default true).
+
+    TypeRegistryReader: minimal get/has surface for ValidateOptions — implemented by @blockml/framework.
+
+    bomEquals(a, b): structural equality modulo provenance (B20).
+    stripProvenance(node): deep-clone omitting sourceLocation, endLine, endColumn, provenance source.
+    Preserves ImplementationBlock.source (code body).
+
+    Sync only. No throw on recoverable diagnostics. Diagnostic distinct from org.blockml.bml.core.Diagnostic.</documentation>
+
+  <references>
+    <see type="bomapi:ParseResult" relation="Defines"></see>
+    <see type="bomapi:ValidateResult" relation="Defines"></see>
+    <see type="bomcap:BomEquals" relation="Defines"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/RelatedDiagnostics.bml

@@ -0,0 +1,51 @@
+<!--
+  BOM Documentation — RelatedDiagnostics
+  FQN: org.blockml.bml.bom.documentation.RelatedDiagnostics
+-->
+<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:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>RelatedDiagnostics</name>
+  <type>bomdocumentation:RelatedDiagnostics</type>
+  <baseType>core:Documentation</baseType>
+  <is>BOM-relevant diagnostic codes</is>
+
+  <documentation>BML_MISSING_BASE_TYPE, BML_MISSING_BLOCK_TYPE, BML_BLOCK_NAME_TYPE_MISMATCH,
+    BML_MISSING_SUBBLOCK_NAME, BML_SUBBLOCK_TYPE_MISMATCH, BML_EMBEDDED_BLOCKS_ON_SUBBLOCK,
+    BML_NESTED_EMBEDDED_BLOCKS, BML_DUPLICATE_EMBEDDED_BLOCK, BML_DEFINITION_TYPE_MISMATCH,
+    BML_MISSING_EMBEDDED_BLOCK_TYPE, BML_UNQUALIFIED_EMBEDDED_BLOCK_TYPE, BML_AMBIGUOUS_TYPE,
+    BML_CONSTRAINT_*, BML_MISSING_IS, BML_MISSING_DOCUMENTATION, BML_MISSING_ISNOT,
+    BML_MISSING_SUMMARY, BML_DUPLICATE_*, BML_INVALID_SINCE_VERSION, BML_CHANGELOG_VERSION_ORDER,
+    BML_EXAMPLE_*, BML_UNKNOWN_NATURAL_LANGUAGE, BML_MISSING_VERSION, BML_UNKNOWN_VERSION,
+    BML_VERSION_BELOW_LIBRARY, BML_VERSION_MINOR_DRIFT, BML_LIBRARY_NESTING_VIOLATION,
+    BML_MISSING_ID, BML_UNRESOLVABLE_INSTANCE_REF, BML_UNEXPORTED_INSTANCE_REF,
+    BML_NON_STATIC_INSTANCE_REF, BML_DUPLICATE_MEMBER_*, BML_INVALID_PROPERTY_TYPE,
+    BML_UNKNOWN_TYPE, BML_INVALID_DEFINITION_BRANCH, BML_INVALID_TYPE_REFERENCE,
+    BML_UNKNOWN_PROPERTY, BML_UNKNOWN_DIRECTIVE, BML_DIRECTIVE_NOT_ALLOWED,
+    BML_PROPERTY_CYCLE, BML_VISIBILITY_*, BML_FINAL_MEMBER_OVERRIDE, BML_OVERRIDE_*,
+    BML_ABSTRACT_MEMBER_NOT_IMPLEMENTED, BML_READONLY_MEMBER_WRITE, BML_STANDALONE_COMPOSITION,
+    BML_NAMESPACE_*, BML_XML_*, BML_PRESET_CYCLE, BML_GENERIC_*, BML_TYPE_BOUND_NOT_SATISFIED,
+    BML_UNKNOWN_CONTRACT, BML_CONTRACT_*, BML_EXPR_UNKNOWN_PROPERTY.
+
+    Full catalog: org.blockml.bml.diagnostic.* (@blockml/core) and 06_compiler.md.</documentation>
+
+</block>

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

@@ -0,0 +1,47 @@
+<!--
+  BOM Documentation — ScopeExclusions
+  FQN: org.blockml.bml.bom.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
+                      "
+  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:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>ScopeExclusions</name>
+  <type>bomdocumentation:ScopeExclusions</type>
+  <baseType>core:Documentation</baseType>
+  <is>Topics intentionally outside @blockml/bom</is>
+
+  <documentation>Not specified in this library:
+
+    Expression AST node union → 10_expression_language.md
+    Embedded expressions in implementations → 10_expression_language.md
+    BML → BOM mapping algorithm → @blockml/parser, 13_bml_to_bom_mapping.md
+    Framework base types (BML) → @blockml/core, 16_framework_base_types.md
+    ValueType / Language BML → 17_type_system_bml.md
+    Dev setup → 15_dev_setup.md
+    MBOM native params → NativeBlock.bml + com.machineblocks.bml.type.*
+    MBOM → SCAD → 04_types.md, 05_scad_renderer.md
+    ManagedObject / synthetic accessors → 08_managed_object.md
+    Built-in #math / #strings → @blockml/core services
+
+    Also outside Urmodell: EffectiveMemberSet, TypeRegistry (core utilities).</documentation>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/SubBlockAndEmbeddedBlocks.bml

@@ -0,0 +1,45 @@
+<!--
+  BOM Documentation — SubBlockAndEmbeddedBlocks
+  FQN: org.blockml.bml.bom.documentation.SubBlockAndEmbeddedBlocks
+-->
+<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:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>SubBlockAndEmbeddedBlocks</name>
+  <type>bomdocumentation:SubBlockAndEmbeddedBlocks</type>
+  <baseType>core:Documentation</baseType>
+  <is>Sub-Block FQN derivation and inline library embeds</is>
+
+  <documentation>Sub-Blocks omit type in BML by convention. FQN derived recursively:
+    parent.type + "." + name (BML_SUBBLOCK_TYPE_MISMATCH if explicit type differs).
+
+    Sub-Blocks share one BomDocument; may nest arbitrarily. Must not declare embeddedBlocks
+    (BML_EMBEDDED_BLOCKS_ON_SUBBLOCK).
+
+    embeddedBlocks: Inline Library on document root only. Each entry is a virtual .bml file.
+    FQN = fully qualified type element value — not nested under root. No nested embeds
+    (BML_NESTED_EMBEDDED_BLOCKS). Duplicate FQNs → BML_DUPLICATE_EMBEDDED_BLOCK.
+    Shadows library definitions within BomDocument; invisible externally.
+
+    Composition references to embeds must use fully qualified block type.</documentation>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/TypeExpressionsOverview.bml

@@ -0,0 +1,47 @@
+<!--
+  BOM Documentation — TypeExpressionsOverview
+  FQN: org.blockml.bml.bom.documentation.TypeExpressionsOverview
+-->
+<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:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>TypeExpressionsOverview</name>
+  <type>bomdocumentation:TypeExpressionsOverview</type>
+  <baseType>core:Documentation</baseType>
+  <is>Parse-time type expression model</is>
+
+  <documentation>TypeExpression (alias TypeDescriptor in V1) — structured parse-time AST, not a ValueType.
+    Used for Capability inputType/outputType and Property type attributes.
+
+    Union variants: named, union, genericParam, self, anonymousStruct.
+
+    Anonymous struct = shorthand for inline class with ordered fields (FunctionMapping positional order).
+    Single primitive = NamedTypeReference directly — not wrapped in one-field struct.
+
+    Union variant discrimination and AST are validateTypes()/parseExpression() utility results —
+    not stored in Canonical BOM.</documentation>
+
+  <references>
+    <see type="bomtype:TypeExpression" relation="Defines"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/ValidationResponsibilities.bml

@@ -0,0 +1,51 @@
+<!--
+  BOM Documentation — ValidationResponsibilities
+  FQN: org.blockml.bml.bom.documentation.ValidationResponsibilities
+-->
+<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:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>ValidationResponsibilities</name>
+  <type>bomdocumentation:ValidationResponsibilities</type>
+  <baseType>core:Documentation</baseType>
+  <is>Full validator checklist on BomDocument</is>
+
+  <documentation>Parser produces BomDocument. Validator (@blockml/validator + @blockml/framework) checks:
+
+    Member namespace uniqueness; baseType in TypeRegistry; property values inline deep copies;
+    resolveEffectiveMembers for expression refs; effective version (BML_MISSING_VERSION);
+    library block.version >= library.version; bml:version asserts (BML_UNKNOWN_VERSION);
+    cross-instance refs to explicit authored id; qualified FQN::id on public aggregations;
+    bml:each explicit id; Sub-Block qualified/FQN refs; generic param ≠ block/sub-block names;
+    visibility rules; no duplicate visibility-prefix variants; expression types match;
+    preset properties exist; property value cycles; basePresets resolve without cycles;
+    contracts merge order; validateConstraints after resolveEffectiveMembers;
+    readOnly enforcement (BML_READONLY_MEMBER_WRITE); library blocks/deps resolve;
+    no outer library re-export from inner library (BML_LIBRARY_NESTING_VIOLATION).
+
+    Validator does NOT expand directives, assign auto-IDs, or interpret aggregations.</documentation>
+
+  <references>
+    <see type="bomdocumentation:RelatedDiagnostics" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/VersionRules.bml

@@ -0,0 +1,41 @@
+<!--
+  BOM Documentation — VersionRules
+  FQN: org.blockml.bml.bom.documentation.VersionRules
+-->
+<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:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  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:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>VersionRules</name>
+  <type>bomdocumentation:VersionRules</type>
+  <baseType>core:Documentation</baseType>
+  <is>Effective block version and instance version asserts</is>
+
+  <documentation>Definition effectiveBlockVersion = own version | library.version (if exported) | BML_MISSING_VERSION.
+    Block in library: version >= library.version when both declared.
+
+    Same-document Sub-Block refs: bml:version not allowed as resolution hint.
+    External refs: bml:version omitted → registry context; present → exact assert (BML_UNKNOWN_VERSION).
+    Library catalog sugar (readMe, bootstrap, dependencies, blocks): same bml:version rules.
+
+    Framework convention: version only on Library.bml for org.blockml.bml.* / com.machineblocks.bml.*</documentation>
+
+</block>