@blockml/compiler 0.1.0

package/blocks/org/blockml/bml/compiler/runtime/capability/RegisterTarget.bml

@@ -0,0 +1,47 @@
+<!--
+  Compiler Runtime Capability — RegisterTarget
+  FQN: org.blockml.bml.compiler.runtime.capability.RegisterTarget
+-->
+<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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator">
+
+  <name>RegisterTarget</name>
+  <type>runcap:RegisterTarget</type>
+  <baseType>core:Capability</baseType>
+  <is>Register a RenderTarget in the in-memory Target Registry</is>
+
+  <documentation>C3: overwrites same name; registry starts empty — no built-in targets.
+    Validates before store (host programming errors throw): name non-empty; accepts non-empty
+    and only valid CompileScopeKind values; render is a function; validateRequest if set is a function.</documentation>
+
+  <references>
+    <see type="rundocumentation:TargetRegistry" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <target type="runapi:RenderTarget">
+      <documentation>Target to register. (required)</documentation>
+    </target>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/capability/RegisteredTargetNames.bml

@@ -0,0 +1,41 @@
+<!--
+  Compiler Runtime Capability — RegisteredTargetNames
+  FQN: org.blockml.bml.compiler.runtime.capability.RegisteredTargetNames
+-->
+<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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator">
+
+  <name>RegisteredTargetNames</name>
+  <type>runcap:RegisteredTargetNames</type>
+  <baseType>core:Capability</baseType>
+  <is>List registered target names</is>
+
+  <documentation>Returns keys of the in-memory registry map.</documentation>
+
+  <properties>
+    <result type="type:Text">
+      <documentation>Target name list. (required)</documentation>
+    </result>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/capability/ResolveScope.bml

@@ -0,0 +1,54 @@
+<!--
+  Compiler Runtime Capability — ResolveScope
+  FQN: org.blockml.bml.compiler.runtime.capability.ResolveScope
+-->
+<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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator">
+
+  <name>ResolveScope</name>
+  <type>runcap:ResolveScope</type>
+  <baseType>core:Capability</baseType>
+  <is>Resolve CompileScope to ResolvedScope or empty diagnostic</is>
+
+  <documentation>C7: document requires document; library/corpus use scope fields then ScopeConfigHints; auto prefers libraries then roots; empty → BML_COMPILE_SCOPE_EMPTY.</documentation>
+
+  <references>
+    <see type="rundocumentation:CompileScopeRules" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <scope type="runapi:CompileScope">
+      <documentation>Input scope. (required)</documentation>
+    </scope>
+    <hints type="runapi:ScopeConfigHints">
+      <documentation>Host hints. (optional)</documentation>
+    </hints>
+    <resolved type="runapi:ResolvedScope">
+      <documentation>Concrete scope or null. (optional)</documentation>
+    </resolved>
+    <diagnostics type="type:Text">
+      <documentation>Scope diagnostics. (required)</documentation>
+    </diagnostics>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/capability/ScopeAccepts.bml

@@ -0,0 +1,51 @@
+<!--
+  Compiler Runtime Capability — ScopeAccepts
+  FQN: org.blockml.bml.compiler.runtime.capability.ScopeAccepts
+-->
+<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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator">
+
+  <name>ScopeAccepts</name>
+  <type>runcap:ScopeAccepts</type>
+  <baseType>core:Capability</baseType>
+  <is>Whether a resolved kind is accepted by a target accepts list</is>
+
+  <documentation>True if accepts includes the resolved kind; also true if accepts includes auto and kind is library or corpus.</documentation>
+
+  <references>
+    <see type="rundocumentation:CompileScopeRules" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <resolvedKind type="type:Text">
+      <documentation>document | library | corpus. (required)</documentation>
+    </resolvedKind>
+    <accepts type="type:Text">
+      <documentation>Target accepts array. (required)</documentation>
+    </accepts>
+    <result type="type:Boolean">
+      <documentation>True if accepted. (required)</documentation>
+    </result>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/capability/ValidateRegistryDocuments.bml

@@ -0,0 +1,51 @@
+<!--
+  Compiler Runtime Capability — ValidateRegistryDocuments
+  FQN: org.blockml.bml.compiler.runtime.capability.ValidateRegistryDocuments
+-->
+<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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator">
+
+  <name>ValidateRegistryDocuments</name>
+  <type>runcap:ValidateRegistryDocuments</type>
+  <baseType>core:Capability</baseType>
+  <is>Re-validate BomDocuments in a TypeRegistry</is>
+
+  <documentation>Dedupes by filePath; optional filePaths filter; continueOnError true.</documentation>
+
+  <references>
+    <see type="validator:Library" relation="SeeAlso" />
+  </references>
+
+  <properties>
+    <typeRegistry type="type:Text">
+      <documentation>TypeRegistry. (required)</documentation>
+    </typeRegistry>
+    <filePaths type="type:Text">
+      <documentation>Optional path filter. (optional)</documentation>
+    </filePaths>
+    <result type="type:Text">
+      <documentation>Diagnostic list. (required)</documentation>
+    </result>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/config/RuntimeConstants.bml

@@ -0,0 +1,43 @@
+<!--
+  Compiler Runtime Config — RuntimeConstants
+  FQN: org.blockml.bml.compiler.runtime.config.RuntimeConstants
+-->
+<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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator">
+
+  <name>RuntimeConstants</name>
+  <type>runconfig:RuntimeConstants</type>
+  <baseType>runtime:RuntimeType</baseType>
+  <is>Well-known diagnostic codes and scope kind literals</is>
+
+  <documentation>Codes emitted by ResolveScope and CompileToOutput / CompileBomToOutput.
+    Scope kinds mirror CompileScopeKind.</documentation>
+  <properties>
+    <BML_UNKNOWN_TARGET type="type:Text"><documentation>Unknown render target name.</documentation></BML_UNKNOWN_TARGET>
+    <BML_TARGET_SCOPE_MISMATCH type="type:Text"><documentation>Resolved scope kind not in target.accepts.</documentation></BML_TARGET_SCOPE_MISMATCH>
+    <BML_COMPILE_SCOPE_EMPTY type="type:Text"><documentation>Missing document/libraries/roots or auto found nothing.</documentation></BML_COMPILE_SCOPE_EMPTY>
+    <BML_MISSING_TYPE_REGISTRY type="type:Text"><documentation>compileBomToOutput requires typeRegistry.</documentation></BML_MISSING_TYPE_REGISTRY>
+    <SCOPE_KINDS type="type:Text"><documentation>document, library, corpus, auto</documentation></SCOPE_KINDS>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/documentation/ArchitectureOverview.bml

@@ -0,0 +1,49 @@
+<!--
+  Compiler Runtime Documentation — ArchitectureOverview
+  FQN: org.blockml.bml.compiler.runtime.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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>ArchitectureOverview</name>
+  <type>rundocumentation:ArchitectureOverview</type>
+  <baseType>core:Documentation</baseType>
+  <is>Modules and compileToOutput data flow</is>
+
+  <documentation>Public modules map to capabilities:
+    types.ts → api/*; target-registry.ts → Register/Get/Clear/RegisteredTargetNames;
+    scope.ts → ResolveScope, ScopeAccepts;
+    compile-bml-to-bom.ts → CompileBmlToBom, ValidateRegistryDocuments;
+    compile-to-output.ts → CompileToOutput (+ sugar);
+    render-context.ts → BuildRenderSession, CreateRenderContext.
+
+    CompileToOutput pipeline: getTarget → validateRequest? → ResolveScope → ScopeAccepts →
+    bootstrapForScope (document parse/register or framework bootstrapTypeRegistry) →
+    document ValidateRegistryDocuments → BuildRenderSession → CreateRenderContext → render.</documentation>
+  <references>
+    <see type="rundocumentation:V1Scope" relation="ReadNext"></see>
+    <see type="runcap:CompileToOutput" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/documentation/CompileIO.bml

@@ -0,0 +1,44 @@
+<!--
+  Compiler Runtime Documentation — CompileIO
+  FQN: org.blockml.bml.compiler.runtime.documentation.CompileIO
+-->
+<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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>CompileIO</name>
+  <type>rundocumentation:CompileIO</type>
+  <baseType>core:Documentation</baseType>
+  <is>Compile I/O model (C4)</is>
+
+  <documentation>C4: BlockML has no mandatory input↔output cardinality. Targets decide how many files
+    (including zero) and may attach side fields on RenderOutput subtypes.
+    Hosts write files; the compiler returns opaque RenderOutput.
+    MachineBlocks 1 BML → 1 SCAD is a domain convention, not a compiler rule.
+    TypeRegistry population follows resolved scope (document vs library vs corpus), not a fixed I/O map.</documentation>
+  <references>
+    <see type="rundocumentation:CompileScopeRules" relation="ReadNext"></see>
+    <see type="runapi:RenderOutput" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/documentation/CompileScopeRules.bml

@@ -0,0 +1,46 @@
+<!--
+  Compiler Runtime Documentation — CompileScopeRules
+  FQN: org.blockml.bml.compiler.runtime.documentation.CompileScopeRules
+-->
+<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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>CompileScopeRules</name>
+  <type>rundocumentation:CompileScopeRules</type>
+  <baseType>core:Documentation</baseType>
+  <is>Compile scope resolution and accepts (C7)</is>
+
+  <documentation>Kinds: document | library | corpus | auto.
+    ResolveScope: document requires scope.document; library uses libraries then hints.libraries;
+    corpus uses roots then hints.roots; auto prefers libraries then roots; else BML_COMPILE_SCOPE_EMPTY.
+    ScopeAccepts: exact kind match, or accepts includes auto and kind is library or corpus.
+    CompileToOutput rejects with BML_TARGET_SCOPE_MISMATCH when ScopeAccepts is false.
+    Accepts matrix for concrete targets lives in target libraries / CLI TargetCliMatrix — not here.</documentation>
+  <references>
+    <see type="rundocumentation:TargetRegistry" relation="ReadNext"></see>
+    <see type="runcap:ResolveScope" relation="SeeAlso"></see>
+    <see type="runcap:ScopeAccepts" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/documentation/DesignDecisions.bml

@@ -0,0 +1,47 @@
+<!--
+  Compiler Runtime Documentation — DesignDecisions
+  FQN: org.blockml.bml.compiler.runtime.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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>DesignDecisions</name>
+  <type>rundocumentation:DesignDecisions</type>
+  <baseType>core:Documentation</baseType>
+  <is>Normative Phase C decisions C1–C7</is>
+
+  <documentation>C1 RenderContext = RenderSession plus forked per-node context; internal render API.
+    C2 Facade = compileToOutput(CompileRequest, …); compileBmlToOutput is document sugar;
+    compileBomToOutput is BOM-first with required TypeRegistry (no re-parse/bootstrap).
+    C3 Registry has no defaults; hosts register; targets[] bootstrap is CLI config (cross-ref);
+    registerTarget validates name, accepts, render.
+    C4 No mandatory input↔output mapping; RenderOutput opaque (files[] base).
+    C5 Incremental build is CLI-only (boundary); not a runtime capability.
+    C6 Thumbnails are CLI-only; not part of RenderOutput.
+    C7 Scope document | library | corpus | auto; accepts[]; opaque targetOptions.</documentation>
+  <references>
+    <see type="rundocumentation:PackageOwnership" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/documentation/Diagnostics.bml

@@ -0,0 +1,47 @@
+<!--
+  Compiler Runtime Documentation — Diagnostics
+  FQN: org.blockml.bml.compiler.runtime.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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>Diagnostics</name>
+  <type>rundocumentation:Diagnostics</type>
+  <baseType>core:Documentation</baseType>
+  <is>Compiler envelope diagnostic codes</is>
+
+  <documentation>Runtime-owned codes:
+    BML_UNKNOWN_TARGET — getTarget missed.
+    BML_TARGET_SCOPE_MISMATCH — resolved kind not accepted.
+    BML_COMPILE_SCOPE_EMPTY — missing document/libraries/roots or auto empty.
+    BML_MISSING_TYPE_REGISTRY — compileBomToOutput called without typeRegistry.
+    Parse/validate diagnostics are forwarded from parser/validator.
+    success on CompilerResult is false if any diagnostic has severity error.
+    CLI maps diagnostics to exit codes — not modeled here.</documentation>
+  <references>
+    <see type="rundocumentation:DesignDecisions" relation="ReadNext"></see>
+    <see type="runconfig:RuntimeConstants" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/documentation/ExternalTargetContract.bml

@@ -0,0 +1,63 @@
+<!--
+  Compiler Runtime Documentation — ExternalTargetContract
+  FQN: org.blockml.bml.compiler.runtime.documentation.ExternalTargetContract
+-->
+<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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>ExternalTargetContract</name>
+  <type>rundocumentation:ExternalTargetContract</type>
+  <baseType>core:Documentation</baseType>
+  <is>Normative contract for external Stage-3 RenderTargets</is>
+
+  <documentation>RenderTarget: name, accepts[], optional validateRequest, render(request, ctx) → RenderOutput
+    (files[] required; optional rootFiles[] at project root, optional diagnostics[] for CLI merge).
+    BOM-first hosts call compileBomToOutput(document, targetName, CompileBomOptions) with a required
+    TypeRegistry; no re-parse or bootstrap. Host must ensure the document is discoverable in the
+    registry when the target looks up by sourceFilePath or FQN.
+
+    Stable RenderSession fields for registry targets: typeRegistry, sourceFilePath, outputBasePath,
+    targetName, scopeKind, libraryPaths?, corpusRoots?.
+    Per-node RenderContext fields (blockFqn, outputRelativePath, child) are for composition renderers;
+    registry targets may ignore them.
+
+    Domain-specific options (MachineBlocks lib path, active config profiles, …) live in opaque
+    targetOptions on CompileRequest / CompileBomOptions — not on CompileOptions or RenderSession.
+    Hosts register targets via registerTarget before compile.
+
+    Stage-2 guarantee: hosts should run validate() or validateRegistryDocuments on the corpus
+    before emit when targets depend on semantic guarantees (embedded blocks, constraints,
+    instance refs).     BlockDoc/XSD compile paths may omit full corpus Stage-2 by policy;
+    blockml validate remains SSOT for semantic validation.
+
+    @blockml/lsp (V1) — editor-agnostic stdio language server (blockml-lsp);
+    IDE clients connect via LSP. See org.blockml.bml.lsp.documentation.Introduction.</documentation>
+  <references>
+    <see type="rundocumentation:Diagnostics" relation="ReadNext"></see>
+    <see type="runapi:RenderTarget" relation="SeeAlso"></see>
+    <see type="runcap:CompileBomToOutput" relation="SeeAlso"></see>
+    <see type="rundocumentation:TargetRegistry" relation="SeeAlso"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/compiler/runtime/documentation/Introduction.bml

@@ -0,0 +1,49 @@
+<!--
+  Compiler Runtime Documentation — Introduction
+  FQN: org.blockml.bml.compiler.runtime.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:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:cli="org.blockml.bml.cli"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:parser="org.blockml.bml.compiler.parser"
+  xmlns:runtime="org.blockml.bml.compiler.runtime"
+  xmlns:runapi="org.blockml.bml.compiler.runtime.api"
+  xmlns:runcap="org.blockml.bml.compiler.runtime.capability"
+  xmlns:runconfig="org.blockml.bml.compiler.runtime.config"
+  xmlns:rundocumentation="org.blockml.bml.compiler.runtime.documentation"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:validator="org.blockml.bml.compiler.validator"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>Introduction</name>
+  <type>rundocumentation:Introduction</type>
+  <baseType>core:Documentation</baseType>
+  <is>Purpose and scope of the compiler runtime</is>
+
+  <documentation>The @blockml/compiler package implements the Stage-3 facade and Target Registry.
+    Normative entry is compileToOutput (C2). Targets register via registerTarget; the
+    registry ships with no defaults (C3). Compile scope kinds and auto resolution are C7.
+
+    This library (org.blockml.bml.compiler.runtime.*) is the SSOT. TypeScript in
+    packages/compiler/src/ implements it. Tests in packages/compiler/test/ encode contracts.
+
+    Host wiring (targets[] bootstrap, file write, exit codes, C5/C6) lives in
+    org.blockml.bml.cli.*. Target emit rules live in each target library.
+    Parser/validator algorithms live in their own libraries; this package orchestrates them.</documentation>
+  <references>
+    <see type="rundocumentation:LayerSeparation" relation="ReadNext"></see>
+    <see type="runcap:CompileToOutput" relation="SeeAlso"></see>
+  </references>
+
+</block>