feat: add C# and optimized .NET compilation backends

.github/workflows/ci-main.yml

@@ -29,6 +29,9 @@ jobs:
         with:
           dotnet-version: 10.0.401
 
+      - name: Install Native AOT toolchain
+        run: sudo apt-get update && sudo apt-get install -y clang zlib1g-dev
+
       - name: Restore
         run: dotnet restore FScript.sln
 

.github/workflows/ci-pr.yml

@@ -35,6 +35,9 @@ jobs:
         with:
           dotnet-version: 10.0.401
 
+      - name: Install Native AOT toolchain
+        run: sudo apt-get update && sudo apt-get install -y clang zlib1g-dev
+
       - name: Restore
         run: dotnet restore FScript.sln
 

.gitignore

@@ -37,6 +37,7 @@ TestResults/
 .DS_Store
 Thumbs.db
 .out
+/out/
 
 vscode-fscript/dist/
 vscode-fscript/*.vsix

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to FScript are documented in this file.
 
 ## [Unreleased]
 
+- Added C# and .NET compilation with FFI support, self-contained executables, and Native AOT publishing.
+- Added typed HIR/LIR, versioned `.fsir` artifacts, and a reference LIR interpreter, with specialization, `Pure`-guided pruning, common-subexpression elimination, and .NET tail-call optimizations.
+- Added execution-local `Env.setExitCode` and `--no-result` controls, and updated the website and documentation for compilation and embedding.
+
 ## [0.83.3]
 
 

FScript.sln

@@ -7,12 +7,16 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{827E0CD3-B72
 EndProject
 Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Language", "src\FScript.Language\FScript.Language.fsproj", "{73C9C013-4E93-45EC-A69D-E490788D8E2B}"
 EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Compiler", "src\FScript.Compiler\FScript.Compiler.fsproj", "{D2D66D0D-2D54-4B13-A847-C94732038E17}"
+EndProject
 Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript", "src\FScript\FScript.fsproj", "{56151E59-268A-4A4B-BE94-B7AD2E8B32FA}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{0AB3BF05-4346-4AA6-1389-037BE0695223}"
 EndProject
 Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Language.Tests", "tests\FScript.Language.Tests\FScript.Language.Tests.fsproj", "{9C62883E-EFB0-4D9E-84F3-4138C123F55E}"
 EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Compiler.Tests", "tests\FScript.Compiler.Tests\FScript.Compiler.Tests.fsproj", "{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}"
+EndProject
 Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Runtime", "src\FScript.Runtime\FScript.Runtime.fsproj", "{8C2C5767-857A-44B0-80C2-DC90E0A60F4D}"
 EndProject
 Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Runtime.Tests", "tests\FScript.Runtime.Tests\FScript.Runtime.Tests.fsproj", "{1E2C7B34-04B8-42C9-880D-CC47DEC156A7}"
@@ -43,6 +47,18 @@ Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Cli.Tests.Fixtures.
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "FScript.DebugAdapter", "src\FScript.DebugAdapter\FScript.DebugAdapter.csproj", "{FE5D4A9E-1936-489C-B489-8133DB47E063}"
 EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Interpreter.Lir", "src\FScript.Interpreter.Lir\FScript.Interpreter.Lir.fsproj", "{88B1BFFA-B93F-49FE-8C70-AB070A21135F}"
+EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Interpreter.Lir.Tests", "tests\FScript.Interpreter.Lir.Tests\FScript.Interpreter.Lir.Tests.fsproj", "{CCC7F576-D284-4B29-A30F-9685929F4E36}"
+EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Conformance.Tests", "tests\FScript.Conformance.Tests\FScript.Conformance.Tests.fsproj", "{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}"
+EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Backend.CSharp", "src\FScript.Backend.CSharp\FScript.Backend.CSharp.fsproj", "{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}"
+EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Backend.DotNet", "src\FScript.Backend.DotNet\FScript.Backend.DotNet.fsproj", "{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}"
+EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FScript.Backend.DotNet.Tests", "tests\FScript.Backend.DotNet.Tests\FScript.Backend.DotNet.Tests.fsproj", "{65E0671A-8A76-4E25-979E-BCA7D57DF84E}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -65,6 +81,18 @@ Global
 		{73C9C013-4E93-45EC-A69D-E490788D8E2B}.Release|x64.Build.0 = Release|Any CPU
 		{73C9C013-4E93-45EC-A69D-E490788D8E2B}.Release|x86.ActiveCfg = Release|Any CPU
 		{73C9C013-4E93-45EC-A69D-E490788D8E2B}.Release|x86.Build.0 = Release|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Debug|x64.Build.0 = Debug|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Debug|x86.Build.0 = Debug|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Release|x64.ActiveCfg = Release|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Release|x64.Build.0 = Release|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Release|x86.ActiveCfg = Release|Any CPU
+		{D2D66D0D-2D54-4B13-A847-C94732038E17}.Release|x86.Build.0 = Release|Any CPU
 		{56151E59-268A-4A4B-BE94-B7AD2E8B32FA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{56151E59-268A-4A4B-BE94-B7AD2E8B32FA}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{56151E59-268A-4A4B-BE94-B7AD2E8B32FA}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -89,6 +117,18 @@ Global
 		{9C62883E-EFB0-4D9E-84F3-4138C123F55E}.Release|x64.Build.0 = Release|Any CPU
 		{9C62883E-EFB0-4D9E-84F3-4138C123F55E}.Release|x86.ActiveCfg = Release|Any CPU
 		{9C62883E-EFB0-4D9E-84F3-4138C123F55E}.Release|x86.Build.0 = Release|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Debug|x64.Build.0 = Debug|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Debug|x86.Build.0 = Debug|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Release|Any CPU.Build.0 = Release|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Release|x64.ActiveCfg = Release|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Release|x64.Build.0 = Release|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Release|x86.ActiveCfg = Release|Any CPU
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B}.Release|x86.Build.0 = Release|Any CPU
 		{8C2C5767-857A-44B0-80C2-DC90E0A60F4D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{8C2C5767-857A-44B0-80C2-DC90E0A60F4D}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{8C2C5767-857A-44B0-80C2-DC90E0A60F4D}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -245,14 +285,88 @@ Global
 		{FE5D4A9E-1936-489C-B489-8133DB47E063}.Release|x64.Build.0 = Release|Any CPU
 		{FE5D4A9E-1936-489C-B489-8133DB47E063}.Release|x86.ActiveCfg = Release|Any CPU
 		{FE5D4A9E-1936-489C-B489-8133DB47E063}.Release|x86.Build.0 = Release|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Debug|x64.Build.0 = Debug|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Debug|x86.Build.0 = Debug|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Release|Any CPU.Build.0 = Release|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Release|x64.ActiveCfg = Release|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Release|x64.Build.0 = Release|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Release|x86.ActiveCfg = Release|Any CPU
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F}.Release|x86.Build.0 = Release|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Debug|x64.Build.0 = Debug|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Debug|x86.Build.0 = Debug|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Release|Any CPU.Build.0 = Release|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Release|x64.ActiveCfg = Release|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Release|x64.Build.0 = Release|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Release|x86.ActiveCfg = Release|Any CPU
+		{CCC7F576-D284-4B29-A30F-9685929F4E36}.Release|x86.Build.0 = Release|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Debug|x64.Build.0 = Debug|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Debug|x86.Build.0 = Debug|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Release|x64.ActiveCfg = Release|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Release|x64.Build.0 = Release|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Release|x86.ActiveCfg = Release|Any CPU
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC}.Release|x86.Build.0 = Release|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Debug|x64.Build.0 = Debug|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Debug|x86.Build.0 = Debug|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Release|Any CPU.Build.0 = Release|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Release|x64.ActiveCfg = Release|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Release|x64.Build.0 = Release|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Release|x86.ActiveCfg = Release|Any CPU
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146}.Release|x86.Build.0 = Release|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Debug|x64.Build.0 = Debug|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Debug|x86.Build.0 = Debug|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Release|Any CPU.Build.0 = Release|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Release|x64.ActiveCfg = Release|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Release|x64.Build.0 = Release|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Release|x86.ActiveCfg = Release|Any CPU
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A}.Release|x86.Build.0 = Release|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Debug|x64.Build.0 = Debug|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Debug|x86.Build.0 = Debug|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Release|Any CPU.Build.0 = Release|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Release|x64.ActiveCfg = Release|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Release|x64.Build.0 = Release|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Release|x86.ActiveCfg = Release|Any CPU
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{73C9C013-4E93-45EC-A69D-E490788D8E2B} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{D2D66D0D-2D54-4B13-A847-C94732038E17} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{56151E59-268A-4A4B-BE94-B7AD2E8B32FA} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{9C62883E-EFB0-4D9E-84F3-4138C123F55E} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
+		{61460CC8-4B1A-4A32-B95B-85DF17DCC54B} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
 		{8C2C5767-857A-44B0-80C2-DC90E0A60F4D} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{1E2C7B34-04B8-42C9-880D-CC47DEC156A7} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
 		{B734E1E1-59C2-47E0-8D19-A9C5C95938F1} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
@@ -267,5 +381,11 @@ Global
 		{CCD6A5F1-38D4-4719-9BB2-B17BB4E2D423} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
 		{D5E47861-ECF0-4678-8B8E-4B30B4FFC52C} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
 		{FE5D4A9E-1936-489C-B489-8133DB47E063} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{88B1BFFA-B93F-49FE-8C70-AB070A21135F} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{CCC7F576-D284-4B29-A30F-9685929F4E36} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
+		{A5495111-E8DD-4862-BF4E-BE13CB96F9DC} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
+		{2BDE00DA-0440-4AB4-8E42-DB0F690CC146} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{32CFD1D1-1087-4275-8D15-73EC0D4CEA9A} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{65E0671A-8A76-4E25-979E-BCA7D57DF84E} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
 	EndGlobalSection
 EndGlobal

Makefile

@@ -35,6 +35,7 @@ smoke-tests:
 	dotnet run --project src/FScript -- samples/ffi/main.fss -- --headless; \
 	echo "All smoke tests passed."
 
+
 verify-changelog:
 	REQUIRE_CHANGELOG_ALWAYS=true .github/scripts/check-unreleased-changelog.sh
 

README.md

@@ -20,6 +20,12 @@ It is designed for host applications that need:
 - **Host-first extensibility**: add external functions with explicit type schemes and runtime implementations.
 - **Security-aware embedding**: script capabilities are defined by what the host exposes.
 
+## Compilation
+
+FScript also compiles to optimized .NET assemblies and independently buildable C# projects. The .NET backend supports self-contained single-file and Native AOT executables, including typed FFI bindings.
+
+See [Compilation](docs/guides/compilation.md) for target selection, [.NET output](docs/guides/compile-to-dotnet.md), [C# projects](docs/guides/compile-to-csharp.md), and [optimization behavior](docs/guides/compiler-optimizations.md).
+
 ## Language Snapshot
 
 FScript currently includes:

docs/README.md

@@ -13,6 +13,15 @@ This folder is organized into three layers:
 - FScript vs F# / OCaml: [`guides/fsharp-ocaml-differences.md`](./guides/fsharp-ocaml-differences.md)
 - Language rationale: [`guides/language-choices.md`](./guides/language-choices.md)
 
+## Compilation
+
+- [Choose a compilation target](./guides/compilation.md)
+- [Compile to .NET](./guides/compile-to-dotnet.md): assemblies, single-file executables, Native AOT, and typed FFI
+- [Compile to C#](./guides/compile-to-csharp.md): generated projects, source layout, and managed references
+- [Compilation and optimizations](./guides/compiler-optimizations.md): shared passes, assembly-only transformations, and pruning limits
+- [Compiler CLI reference](./guides/compiler-cli.md)
+- [Compile and interpret IR](./guides/interpret-ir.md)
+
 ## User references
 
 The [website manual sources](../website/docs/intro.md) separate a guided learning path from lookup material:

docs/architecture/README.md

@@ -4,3 +4,4 @@ How the repository and assemblies are organized.
 
 - Assemblies and roles: [`assemblies-and-roles.md`](./assemblies-and-roles.md)
 - REPL architecture: [`repl-architecture.md`](./repl-architecture.md)
+- Typed IR and backends: [`typed-ir-and-backends.md`](./typed-ir-and-backends.md)

docs/architecture/assemblies-and-roles.md

@@ -38,6 +38,38 @@ Use this when:
 - You want to embed the language in another .NET application.
 - You need language processing independently from default runtime extern catalog.
 
+### `FScript.Compiler`
+Role:
+- Reusable .NET compiler pipeline for typed HIR, executable LIR, and IR artifacts.
+
+Responsibilities:
+- Consume the resolved typed result produced by `FScript.Language`.
+- Validate and lower HIR to backend-independent LIR.
+- Serialize and validate whole-program `.fsir` artifacts.
+
+`FScript.Compiler` depends on `FScript.Language` and is intentionally excluded from the Fable JavaScript package.
+
+### `FScript.Interpreter.Lir`
+Role:
+- Backend-independent execution engine for validated LIR.
+
+Responsibilities:
+- Execute LIR values, closures, decision trees, aggregates, intrinsics, and failures.
+- Validate caller-provided LIR and return one structured execution diagnostic on failure.
+- Supply script identity and arguments through `InterpreterContext`.
+- Reject reachable unsupported target or host linkage with interpreter diagnostics.
+
+`FScript.Interpreter.Lir` depends on `FScript.Compiler`; the core compiler has no dependency on the interpreter.
+
+### `FScript.Backend.CSharp` and `FScript.Backend.DotNet`
+Role:
+- Consume validated LIR to emit an independent C# project or optimized .NET assembly.
+- Share concrete HM specialization and simplification in `FScript.Compiler`.
+- Bind FFI calls and external types to the CLR; report target-specific diagnostics.
+- Optionally publish self-contained or Native AOT executables through the .NET SDK.
+
+Consumer tests follow the same boundary: `FScript.Interpreter.Lir.Tests` owns LIR execution; `FScript.Backend.DotNet.Tests` owns native generation. `FScript.Compiler.Tests` covers HIR, lowering, LIR validation, and artifacts.
+
 NuGet:
 - `MagnusOpera.FScript.Language`
 
@@ -141,11 +173,14 @@ Use this when:
 
 ## Dependency direction
 - `FScript.Language` has no dependency on `FScript.Runtime`.
+- `FScript.Compiler` depends only on `FScript.Language`.
+- `FScript.Interpreter.Lir` and `FScript.Backend.CSharp` each depend on `FScript.Compiler`.
+- `FScript.Backend.CSharp` depends on `FScript.Compiler`; `FScript.Backend.DotNet` uses that emitter and Roslyn to produce PE assemblies.
 - `FScript.JavaScript` depends on `FScript.Language` and Fable packages.
 - `FScript.Runtime` depends on `FScript.Language` types.
 - `FScript.CSharpInterop` depends on both `FScript.Language` and `FScript.Runtime`.
 - `FScript.LanguageServer` depends on `FScript.CSharpInterop`.
-- `FScript` depends on both `FScript.Language` and `FScript.Runtime`.
+- `FScript` depends on `FScript.Language`, `FScript.Runtime`, `FScript.Compiler`, `FScript.Interpreter.Lir`, `FScript.Backend.CSharp`, and `FScript.Backend.DotNet`.
 
 This keeps the language engine reusable while runtime capabilities remain host-configurable. The JavaScript facade is intentionally separate from `.NET` runtime externs: v1 exposes core language hosting, virtual imports, tagged values, and JS-provided externs, while filesystem, console, task, and other runtime modules stay in the .NET runtime layer.