@blockml/fatblock-target 0.1.0

package/blocks/org/blockml/bml/target/fatblock/capability/Render.bml

@@ -0,0 +1,49 @@
+<!--
+  FatBlock Capability — Render
+  FQN: org.blockml.bml.target.fatblock.capability.Render
+-->
+<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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>Render</name>
+  <type>fbcap:Render</type>
+  <baseType>core:Capability</baseType>
+  <is>Public RenderTarget entry: host document to Host.fat.bml</is>
+
+  <documentation>FB2: name fatblock; accepts document only. FB4: assemble errors or serialize errors yield empty files. Strip info diagnostics from returned list. Orchestrates ResolveOptions, AssembleFatDocument, SerializeFatDocument, FatOutputBasename.</documentation>
+
+  <references>
+    <see type="fbdocumentation:PublicApi" relation="SeeAlso" />
+    <see type="fbcap:AssembleFatDocument" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <request type="type:Text">
+      <documentation>CompileRequest with targetOptions. (required)</documentation>
+    </request>
+    <renderContext type="type:Text">
+      <documentation>RenderContext with typeRegistry and sourceFilePath. (required)</documentation>
+    </renderContext>
+    <result type="fbapi:FatBlockRenderOutput">
+      <documentation>files and diagnostics. (required)</documentation>
+    </result>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/capability/ResolveOptions.bml

@@ -0,0 +1,46 @@
+<!--
+  FatBlock Capability — ResolveOptions
+  FQN: org.blockml.bml.target.fatblock.capability.ResolveOptions
+-->
+<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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>ResolveOptions</name>
+  <type>fbcap:ResolveOptions</type>
+  <baseType>core:Capability</baseType>
+  <is>Merge opaque targetOptions into FatBlockOptions with defaults</is>
+
+  <documentation>FB1: embeddedBlocksStrategy defaults to error. srcDir, rootDir, include passed through when present.</documentation>
+
+  <references>
+    <see type="fbdocumentation:PublicApi" relation="SeeAlso" />
+    <see type="fbconfig:DefaultFatBlockOptions" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <targetOptions type="type:Text">
+      <documentation>Opaque CompileRequest.targetOptions. (optional)</documentation>
+    </targetOptions>
+    <result type="fbapi:FatBlockOptions">
+      <documentation>Resolved options. (required)</documentation>
+    </result>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/capability/RootFqnsByFilePath.bml

@@ -0,0 +1,45 @@
+<!--
+  FatBlock Capability — RootFqnsByFilePath
+  FQN: org.blockml.bml.target.fatblock.capability.RootFqnsByFilePath
+-->
+<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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>RootFqnsByFilePath</name>
+  <type>fbcap:RootFqnsByFilePath</type>
+  <baseType>core:Capability</baseType>
+  <is>Map each source file to its root FQN</is>
+
+  <documentation>FB5: group registry keys by filePath; skip missing or angle-bracket paths; root = FQN not prefixed by another FQN from the same file (subBlocks excluded).</documentation>
+
+  <references>
+    <see type="fbdocumentation:CandidateCollection" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <typeRegistry type="type:Text">
+      <documentation>TypeRegistry. (required)</documentation>
+    </typeRegistry>
+    <result type="type:Text">
+      <documentation>Map filePath to root FQN. (required)</documentation>
+    </result>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/capability/SerializeFatDocument.bml

@@ -0,0 +1,48 @@
+<!--
+  FatBlock Capability — SerializeFatDocument
+  FQN: org.blockml.bml.target.fatblock.capability.SerializeFatDocument
+-->
+<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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>SerializeFatDocument</name>
+  <type>fbcap:SerializeFatDocument</type>
+  <baseType>core:Capability</baseType>
+  <is>Serialize fat BomDocument to canonical BML XML</is>
+
+  <documentation>FB17: call @blockml/serializer serialize(document, { indent: 2 }). Returns text and diagnostics.</documentation>
+
+  <references>
+    <see type="fbdocumentation:OutputLayout" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <document type="bomdoc:BomDocument">
+      <documentation>Assembled fat document. (required)</documentation>
+    </document>
+    <text type="type:Text">
+      <documentation>Serialized XML or null. (optional)</documentation>
+    </text>
+    <diagnostics type="type:Text">
+      <documentation>Serialize diagnostics. (required)</documentation>
+    </diagnostics>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/capability/ValidateRequest.bml

@@ -0,0 +1,45 @@
+<!--
+  FatBlock Capability — ValidateRequest
+  FQN: org.blockml.bml.target.fatblock.capability.ValidateRequest
+-->
+<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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>ValidateRequest</name>
+  <type>fbcap:ValidateRequest</type>
+  <baseType>core:Capability</baseType>
+  <is>Validate CompileRequest before render</is>
+
+  <documentation>FB3: if srcDir missing, return BML_FATBLOCK_SRC_REQUIRED error diagnostic. Otherwise empty list.</documentation>
+
+  <references>
+    <see type="fbdocumentation:Diagnostics" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <request type="type:Text">
+      <documentation>CompileRequest. (required)</documentation>
+    </request>
+    <result type="type:Text">
+      <documentation>Diagnostic[]. (required)</documentation>
+    </result>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/config/DefaultFatBlockOptions.bml

@@ -0,0 +1,35 @@
+<!--
+  FatBlock Config — DefaultFatBlockOptions
+  FQN: org.blockml.bml.target.fatblock.config.DefaultFatBlockOptions
+-->
+<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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>DefaultFatBlockOptions</name>
+  <type>fbconfig:DefaultFatBlockOptions</type>
+  <baseType>fatblock:FatblockType</baseType>
+  <is>Defaults applied by ResolveOptions</is>
+
+  <documentation>FB1: only embeddedBlocksStrategy has a default; srcDir/rootDir/include remain unset until host provides them.</documentation>
+  <properties>
+    <embeddedBlocksStrategy type="type:Text"><documentation>"error"</documentation></embeddedBlocksStrategy>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/config/FatBlockConstants.bml

@@ -0,0 +1,38 @@
+<!--
+  FatBlock Config — FatBlockConstants
+  FQN: org.blockml.bml.target.fatblock.config.FatBlockConstants
+-->
+<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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>FatBlockConstants</name>
+  <type>fbconfig:FatBlockConstants</type>
+  <baseType>fatblock:FatblockType</baseType>
+  <is>Well-known FatBlock constants</is>
+
+  <properties>
+    <REGISTRY_NAME type="type:Text"><documentation>Always "fatblock".</documentation></REGISTRY_NAME>
+    <ACCEPTS type="type:Text"><documentation>document only.</documentation></ACCEPTS>
+    <DEFAULT_EMBEDDED_BLOCKS_STRATEGY type="type:Text"><documentation>"error".</documentation></DEFAULT_EMBEDDED_BLOCKS_STRATEGY>
+    <SERIALIZE_INDENT type="type:Integer"><documentation>2 — passed to @blockml/serializer.</documentation></SERIALIZE_INDENT>
+    <DEFAULT_XMLNS type="type:Text"><documentation>http://blockml.org/bml for empty prefix when bindings omitted.</documentation></DEFAULT_XMLNS>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/documentation/ArchitectureOverview.bml

@@ -0,0 +1,53 @@
+<!--
+  FatBlock Documentation — ArchitectureOverview
+  FQN: org.blockml.bml.target.fatblock.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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>ArchitectureOverview</name>
+  <type>fbdocumentation:ArchitectureOverview</type>
+  <baseType>core:Documentation</baseType>
+  <is>Module map and assemble pipeline</is>
+
+  <documentation>Entry: fbcap:Render (FatBlockTarget.render)
+    → ResolveOptions
+    → AssembleFatDocument (RootFqnsByFilePath, CollectCandidateFqns, FilterByIncludes,
+      CloneBlockDefinition, MergeNamespaceBindings)
+    → SerializeFatDocument
+    → FatOutputBasename
+
+    ValidateRequest runs before render when the host calls it; requires srcDir.
+
+    TypeScript module map:
+    • options.ts → ResolveOptions, FatBlockOptions
+    • collect-candidates.ts → RootFqnsByFilePath, CollectCandidateFqns
+    • filter-includes.ts → MatchesIncludePattern, FilterByIncludes
+    • clone-block.ts → CloneBlockDefinition
+    • merge-namespace-bindings.ts → MergeNamespaceBindings
+    • assemble-fat-document.ts → AssembleFatDocument, SerializeFatDocument
+    • fat-output-path.ts → FatOutputBasename
+    • fatblock-target.ts → Render, ValidateRequest</documentation>
+  <references>
+    <see type="fbdocumentation:V1Scope" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/documentation/CandidateCollection.bml

@@ -0,0 +1,45 @@
+<!--
+  FatBlock Documentation — CandidateCollection
+  FQN: org.blockml.bml.target.fatblock.documentation.CandidateCollection
+-->
+<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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>CandidateCollection</name>
+  <type>fbdocumentation:CandidateCollection</type>
+  <baseType>core:Documentation</baseType>
+  <is>Root FQN selection and include filters (FB5–FB7)</is>
+
+  <documentation>FB5 RootFqnsByFilePath: per source file, root FQN is one not prefixed by another FQN
+    from the same file — Sub-Block registry keys are not embed candidates.
+
+    FB6 CollectCandidateFqns: roots whose file path is under resolve(rootDir, srcDir);
+    exclude host FQN; sort ascending; apply include when non-empty.
+
+    FB7 Include: pattern ending * is prefix match; else exact FQN; OR across patterns;
+    empty/omitted patterns keep all candidates.
+
+    V1 semantics = folder pool, not dependency graph walk.</documentation>
+  <references>
+    <see type="fbdocumentation:EmbedAssemblyRules" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/documentation/DesignDecisions.bml

@@ -0,0 +1,51 @@
+<!--
+  FatBlock Documentation — DesignDecisions
+  FQN: org.blockml.bml.target.fatblock.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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>DesignDecisions</name>
+  <type>fbdocumentation:DesignDecisions</type>
+  <baseType>core:Documentation</baseType>
+  <is>Normative FatBlock decisions FB1–FB20</is>
+
+  <documentation>FB1 ResolveOptions default embeddedBlocksStrategy=error.
+    FB2 accepts document only; registry name fatblock.
+    FB3 ValidateRequest requires srcDir.
+    FB4 render empty files on assemble/serialize errors; strip info diags.
+    FB5 RootFqnsByFilePath excludes Sub-Block FQNs.
+    FB6 CollectCandidateFqns path-under-src; exclude host; sort.
+    FB7 include exact or prefix*; OR; empty=all.
+    FB8 CloneBlockDefinition via structuredClone.
+    FB9 Merge host then embeds.
+    FB10 prefix collision diagnostic; no rewrite.
+    FB11 default empty-prefix xmlns.
+    FB12–FB16 assemble host/embed empty-embeds and not-found rules.
+    FB17 preserve subBlocks; clear nested embeds on clone; serialize indent 2.
+    FB18 Host.fat.bml basename.
+    FB19 V1 = folder pool not transitive closure.
+    FB20 embeddedBlocksStrategy reserved; assemble hardcodes empty-embeds check.</documentation>
+  <references>
+    <see type="fbdocumentation:PackageOwnership" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/documentation/Diagnostics.bml

@@ -0,0 +1,48 @@
+<!--
+  FatBlock Documentation — Diagnostics
+  FQN: org.blockml.bml.target.fatblock.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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>Diagnostics</name>
+  <type>fbdocumentation:Diagnostics</type>
+  <baseType>core:Documentation</baseType>
+  <is>FatBlock-owned and shared diagnostic codes</is>
+
+  <documentation>Owned / emitted by this package:
+    • BML_FATBLOCK_SRC_REQUIRED — missing srcDir
+    • BML_FATBLOCK_HOST_NOT_FOUND — host file not a registry root
+    • BML_FATBLOCK_HOST_HAS_EMBEDDED_BLOCKS — host already has embeds
+    • BML_FATBLOCK_EMBED_NOT_FOUND — candidate missing or not root
+    • BML_FATBLOCK_EMBED_HAS_EMBEDDED_BLOCKS — candidate already has embeds
+    • BML_DUPLICATE_EMBEDDED_BLOCK — same FQN twice in candidates
+    • BML_NAMESPACE_PREFIX_COLLISION — conflicting prefix to URI
+
+    Shared upstream (not reimplemented here): BML_EMBEDDED_BLOCKS_ON_SUBBLOCK,
+    BML_NESTED_EMBEDDED_BLOCKS (validator); BML_NAMESPACE_UNBOUND (serializer).
+
+    Severity: all FatBlock codes are error. CLI exit: config → 2; assemble → 1.</documentation>
+  <references>
+    <see type="fbdocumentation:DesignDecisions" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/documentation/EmbedAssemblyRules.bml

@@ -0,0 +1,46 @@
+<!--
+  FatBlock Documentation — EmbedAssemblyRules
+  FQN: org.blockml.bml.target.fatblock.documentation.EmbedAssemblyRules
+-->
+<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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>EmbedAssemblyRules</name>
+  <type>fbdocumentation:EmbedAssemblyRules</type>
+  <baseType>core:Documentation</baseType>
+  <is>Host and embed assembly invariants (FB12–FB17)</is>
+
+  <documentation>FB12 srcDir required or BML_FATBLOCK_SRC_REQUIRED.
+    FB13 host missing from registry → BML_FATBLOCK_HOST_NOT_FOUND.
+    FB14 host.embeddedBlocks.length greater than 0 → BML_FATBLOCK_HOST_HAS_EMBEDDED_BLOCKS.
+    FB15 duplicate candidate FQN → BML_DUPLICATE_EMBEDDED_BLOCK.
+    FB16 embed must be document root (doc.block.type === fqn) else BML_FATBLOCK_EMBED_NOT_FOUND;
+    embed with non-empty embeddedBlocks → BML_FATBLOCK_EMBED_HAS_EMBEDDED_BLOCKS.
+    FB17 clone each embed; force cloned.embeddedBlocks empty; preserve subBlocks[];
+    attach to host clone in sorted FQN order; merge namespaces; any error aborts document null.
+
+    Meta-model (BOM): embeds are flat under root; Sub-Blocks forbid embeds — validator owns
+    BML_EMBEDDED_BLOCKS_ON_SUBBLOCK / BML_NESTED_EMBEDDED_BLOCKS.</documentation>
+  <references>
+    <see type="fbdocumentation:NamespaceMergeRules" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/documentation/Introduction.bml

@@ -0,0 +1,49 @@
+<!--
+  FatBlock Documentation — Introduction
+  FQN: org.blockml.bml.target.fatblock.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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>Introduction</name>
+  <type>fbdocumentation:Introduction</type>
+  <baseType>core:Documentation</baseType>
+  <is>Purpose and scope of the FatBlock render target</is>
+
+  <documentation>The @blockml/fatblock-target package implements RenderTarget registry name fatblock.
+    It emits one portable .bml file with peer root blocks inlined under the host root
+    embeddedBlocks aggregation (Inline Library model).
+
+    This library (org.blockml.bml.target.fatblock.*) is the SSOT. TypeScript in
+    packages/fatblock-target/src/ implements it. Tests in packages/fatblock-target/test/
+    encode behavioral contracts.
+
+    V1 is a folder-bundle target: document scope, required srcDir (--src) peer pool,
+    optional include FQN filters. Not transitive dependency closure (that is v2).
+
+    Pipeline: ResolveOptions → AssembleFatDocument → SerializeFatDocument → Host.fat.bml.
+    Host CLI wiring (flags, exit codes) lives in org.blockml.bml.cli.*</documentation>
+  <references>
+    <see type="fbdocumentation:LayerSeparation" relation="ReadNext"></see>
+    <see type="fbcap:Render" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/target/fatblock/documentation/LayerSeparation.bml

@@ -0,0 +1,50 @@
+<!--
+  FatBlock Documentation — LayerSeparation
+  FQN: org.blockml.bml.target.fatblock.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:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:fatblock="org.blockml.bml.target.fatblock"
+  xmlns:fbapi="org.blockml.bml.target.fatblock.api"
+  xmlns:fbcap="org.blockml.bml.target.fatblock.capability"
+  xmlns:fbconfig="org.blockml.bml.target.fatblock.config"
+  xmlns:fbdocumentation="org.blockml.bml.target.fatblock.documentation"
+  xmlns:serializer="org.blockml.bml.compiler.serializer"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>LayerSeparation</name>
+  <type>fbdocumentation:LayerSeparation</type>
+  <baseType>core:Documentation</baseType>
+  <is>FatBlock vs BOM vs serializer vs CLI</is>
+
+  <documentation>Layers relevant to FatBlock:
+
+    org.blockml.bml.target.fatblock.* (this package) — candidate collection, include filter,
+    assemble/merge, FatBlockOptions, FatBlock diagnostics, output basename.
+
+    org.blockml.bml.bom.* — embeddedBlocks meta-model; root-only embeds; no nested embeds
+    on Sub-Blocks (validator). FatBlock consumes BomDocument / BlockDefinition.
+
+    org.blockml.bml.compiler.serializer.* — canonical XML emit of the assembled document.
+
+    @blockml/compiler — RenderTarget contract, compileToOutput, document scope.
+
+    org.blockml.bml.cli.* — --src / --include / --out, host file required, write Host.fat.bml.
+
+    Sibling targets (blockdoc, xsd) and domain SCAD are out of scope.</documentation>
+  <references>
+    <see type="fbdocumentation:ArchitectureOverview" relation="ReadNext"></see>
+  </references>
+
+</block>