@blockml/framework 0.1.0

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

@@ -0,0 +1,60 @@
+<!--
+  Framework Documentation — ArchitectureOverview
+  FQN: org.blockml.bml.framework.documentation.ArchitectureOverview
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns: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:doc="org.blockml.bml.documentation">
+
+  <name>ArchitectureOverview</name>
+  <type>fwdocumentation:ArchitectureOverview</type>
+  <baseType>core:Documentation</baseType>
+  <is>Module decomposition for framework utilities</is>
+
+  <documentation>Module decomposition (packages/framework/src/):
+
+    registry/type-registry.ts — fwcap:TypeRegistry (register, get, has, keys, size)
+    registry/bootstrap.ts — fwcap:BootstrapTypeRegistry, fwcap:DefaultBootstrapPaths
+    registry/library-bootstrap.ts — library graph resolution (Library.bml dependencies)
+    fork/fork-bom.ts — fwcap:ForkBom (structuredClone pragmatic copy)
+    resolve/resolve-effective-members.ts — fwcap:ResolveEffectiveMembers,
+      fwcap:ResolveContracts, fwcap:CollectBaseTypeChain, fwcap:MemberIdentityKey
+    expression/parse-expression.ts — fwcap:ParseExpression
+    expression/types.ts — fwexpression:* AST node types
+    validate/validate-types.ts — fwcap:ValidateTypes, fwcap:GetPropertyNumericValue,
+      fwcap:IsLiteralValue
+    validate/validate-versions.ts — fwcap:ValidateVersions
+    validate/validate-constraints.ts — fwcap:ValidateConstraints
+
+    Internal data-structure types extend framework:FrameworkType.
+    Public operations are fwcap:* capabilities.</documentation>
+
+  <references>
+    <see type="fwdocumentation:PublicApi" relation="ReadNext"></see>
+    <see type="fwcap:TypeRegistry" relation="Defines"></see>
+  </references>
+
+</block>

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

@@ -0,0 +1,59 @@
+<!--
+  Framework Documentation — ConstraintValidation
+  FQN: org.blockml.bml.framework.documentation.ConstraintValidation
+-->
+<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:doc="org.blockml.bml.documentation">
+
+  <name>ConstraintValidation</name>
+  <type>fwdocumentation:ConstraintValidation</type>
+  <baseType>core:Documentation</baseType>
+  <is>validateConstraints branch dispatch and embed contexts</is>
+
+  <documentation>validateConstraints evaluates constraints on the effective member set from
+    resolveEffectiveMembers (baseType + contracts + local). Property ValuePresent and other
+    ValueConstraints on effective PropertyDefinition are checked against authored local values.
+
+    Embed contexts for directly declared constraint BlockInstances:
+    block — BlockConstraint (RequiresMember), ValueConstraint (Min/Max/ValuePresent)
+    property — PropertyConstraint (MustBeReadOnly), ValueConstraint
+    aggregation — AggregationConstraint (AllowedChildType)
+    association — AssociationConstraint (NoSelfReference)
+    capability — CapabilityConstraint (RequiresImplementation)
+
+    Wrong branch for context → BML_CONSTRAINT_TARGET_MISMATCH.
+    Unknown constraint type → BML_CONSTRAINT_UNKNOWN.
+    Violation → BML_CONSTRAINT_VIOLATION.
+
+    Fixtures: packages/framework/test/constraints/fixtures/*.bml</documentation>
+
+  <references>
+    <see type="fwdocumentation:Diagnostics" relation="ReadNext"></see>
+    <see type="fwcap:ValidateConstraints" relation="Defines"></see>
+  </references>
+
+</block>

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

@@ -0,0 +1,68 @@
+<!--
+  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
+                      "
+  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: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):
+
+    validateTypes:
+    • BML_UNKNOWN_BASE_TYPE — baseType FQN not in TypeRegistry
+    • BML_UNKNOWN_CONTRACT — contracts[] FQN not in TypeRegistry
+    • 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
+
+    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>
+
+  <references>
+    <see type="fwconfig:FrameworkDiagnosticCodes" relation="Defines"></see>
+    <see type="fwdocumentation:PackageOwnership" relation="ReadNext"></see>
+  </references>
+
+</block>

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

@@ -0,0 +1,61 @@
+<!--
+  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
+                      "
+  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: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:
+
+    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.
+
+    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>
+
+  <references>
+    <see type="fwdocumentation:ExpressionParsing" relation="ReadNext"></see>
+    <see type="fwcap:ResolveEffectiveMembers" relation="Defines"></see>
+    <see type="fwcap:ResolveContracts" relation="SeeAlso"></see>
+  </references>
+
+</block>

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

@@ -0,0 +1,53 @@
+<!--
+  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
+                      "
+  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: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.
+    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.
+
+    AST node kinds: literal, array, object, property, call, binary.
+    Optional resultTypeFqn on ParseExpressionResult for typed expression metadata.
+
+    Expression AST is a Stage-2 utility — never written back to Urmodell member values.</documentation>
+
+  <references>
+    <see type="fwdocumentation:ConstraintValidation" relation="ReadNext"></see>
+    <see type="fwexpression:ExpressionNode" relation="Defines"></see>
+  </references>
+
+</block>

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

@@ -0,0 +1,56 @@
+<!--
+  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
+                      "
+  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: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,
+    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>
+
+  <references>
+    <see type="fwdocumentation:LayerSeparation" relation="ReadNext"></see>
+    <see type="bomdocumentation:Introduction" relation="SeeAlso"></see>
+  </references>
+
+</block>

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

@@ -0,0 +1,59 @@
+<!--
+  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
+                      "
+  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: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:
+
+    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>
+
+  <references>
+    <see type="fwdocumentation:ArchitectureOverview" relation="ReadNext"></see>
+    <see type="bomdocumentation:LayerSeparation" relation="SeeAlso"></see>
+  </references>
+
+</block>

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

@@ -0,0 +1,56 @@
+<!--
+  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
+                      "
+  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: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,
+    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>
+
+  <references>
+    <see type="fwdocumentation:ScopeExclusions" relation="ReadNext"></see>
+    <see type="bomdocumentation:PackageOwnership" relation="SeeAlso"></see>
+  </references>
+
+</block>

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

@@ -0,0 +1,72 @@
+<!--
+  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
+                      "
+  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: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>Public exports from @blockml/framework (packages/framework/src/index.ts):
+
+    TypeRegistry — class; register/get/has/keys/size on BomDocument index
+    bootstrapTypeRegistry(options?) → BootstrapResult
+    defaultBootstrapPaths(rootDir?) → string[]
+    BootstrapOptions — paths?, libraryPaths?, rootDir?
+    rootFqnByFilePath(registry) → Map&lt;filePath, rootFqn&gt;
+    rootFqns(registry) → string[]
+    getExportedFqns(libraryPath, bootstrap, rootDir?) → Set&lt;string&gt; | undefined
+    forkBom(document) → BomDocument
+    resolveEffectiveMembers(block, registry) → MemberDefinition[]
+    resolveContracts(block, registry) → MemberDefinition[] (contract slice; used by resolveEffectiveMembers)
+    collectBaseTypeChain(block, registry) → BlockDefinition[]
+    memberIdentityKey(member) → string
+    parseExpression(source) → ParseExpressionOutcome
+    validateTypes(document, registry) → Diagnostic[]
+    validateEmbeddedBlocks(document) → Diagnostic[]
+    validateVersions(document, registry) → Diagnostic[]
+    validateInstances(document, registry) → Diagnostic[]
+    validatePresets(document, registry) → Diagnostic[]
+    validateVisibility(document, registry) → Diagnostic[]
+    validateReadOnly(document, registry) → Diagnostic[]
+    validateConstraints(document, registry) → Diagnostic[]
+    getPropertyNumericValue(property) → number | undefined
+    isLiteralValue(value) → boolean
+
+    Types: BootstrapResult, BootstrapOptions, ExpressionNode, ParseExpressionResult, ParseExpressionOutcome
+
+    Not exported from index: getLiteralNumericValue (internal helper in validate-types.ts).</documentation>
+
+  <references>
+    <see type="fwdocumentation:TypeRegistryBootstrap" relation="ReadNext"></see>
+    <see type="bomapi:TypeRegistryReader" relation="SeeAlso"></see>
+  </references>
+
+</block>

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

@@ -0,0 +1,52 @@
+<!--
+  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
+                      "
+  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: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:
+
+    • 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>
+
+  <references>
+    <see type="fwdocumentation:Introduction" relation="SeeAlso"></see>
+  </references>
+
+</block>