Morphir.SDK.FSharp 0.5.0-alpha.1

Prefix Reserved
This is a prerelease version of Morphir.SDK.FSharp.
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Morphir.SDK.FSharp --version 0.5.0-alpha.1
                    
NuGet\Install-Package Morphir.SDK.FSharp -Version 0.5.0-alpha.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Morphir.SDK.FSharp" Version="0.5.0-alpha.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Morphir.SDK.FSharp" Version="0.5.0-alpha.1" />
                    
Directory.Packages.props
<PackageReference Include="Morphir.SDK.FSharp" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Morphir.SDK.FSharp --version 0.5.0-alpha.1
                    
#r "nuget: Morphir.SDK.FSharp, 0.5.0-alpha.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Morphir.SDK.FSharp@0.5.0-alpha.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Morphir.SDK.FSharp&version=0.5.0-alpha.1&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Morphir.SDK.FSharp&version=0.5.0-alpha.1&prerelease
                    
Install as a Cake Tool

Morphir.SDK.FSharp

F# runtime library providing Morphir SDK types and functions for generated F# code.

Overview

Morphir.SDK.FSharp provides the F# runtime used by generated Morphir code. Its namespace and runtime assembly remain Morphir.SDK.

Installation

dotnet add package Morphir.SDK.FSharp

Migrating existing consumers

Replace the Morphir.SDK package reference with Morphir.SDK.FSharp, using the same release version. Keep open Morphir.SDK and existing generated source unchanged. Project-reference consumers use src/Morphir.SDK.FSharp/Morphir.SDK.FSharp.fsproj.

The legacy Morphir.SDK package remains installable. It depends on the exact matching canonical package version and contains no runtime assembly. Installing either package or both resolves the same Morphir.SDK.dll. Do not reference the legacy pack-only project as a runtime project dependency.

The migration preserves the Morphir.SDK.Order type identity, existing public entry points and F# aliases. Aliases such as Maybe<'a>, Dict<'k,'v>, LocalDate and LocalTime retain their FSharp.Core/BCL types. They do not become new CLR wrapper or forwarding types.

Select the FSharp.Core version required by the package. The captured baseline uses 11.0.100; a compiler's lower implicit dependency can otherwise cause NU1605 and runtime loading failures. For an SDK whose implicit version is lower:

<PropertyGroup>
  <FSharpCoreImplicitPackageVersion>11.0.100</FSharpCoreImplicitPackageVersion>
  <WarningsAsErrors>$(WarningsAsErrors);NU1605</WarningsAsErrors>
</PropertyGroup>

The bounded conformance contract and migration corrections are tracked in issue #465. Packaging identity preservation does not claim that behavior corrections replace old code already inlined into an existing binary.

Covered behavior changes

The package migration also corrects the cases admitted by the shared morphir-dotnet-sdk-v1 / dotnet-sdk-v1 contract. It does not certify every SDK operation or every host representation.

  • Dict.union left right now keeps left's value for a shared key. Previously the second dictionary won. For example, unioning [("rate", 1)] with [("rate", 9)] now yields [("rate", 1)]. Both operands remain unchanged.
  • Int32 Basics.add, subtract, multiply and negate report overflow instead of wrapping. The generic public entry points remain available.
  • Basics.remainderBy -1 System.Int32.MinValue and Basics.modBy with those operands return zero. Previously the host remainder instruction overflowed.
  • Basics.compare compares direct String operands by ordinal UTF-16 code units, without culture or normalization. For example, decomposed "e\u0301" sorts before precomposed "\u00e9"; they no longer compare equal through collation.
  • Decimal.toString uses invariant positional text and removes fractional trailing zeros. 1.50M becomes "1.5", and scaled zero becomes "0". Decimal.fromString parses this canonical representation first under every culture, then tries the caller's culture for other input. For example, under de-DE, both "1.5" and localized "1,5" mean 1.5M. Ambiguous dot-separated input follows canonical decimal-point semantics rather than localized grouping. Parsing remains a native API compatibility check outside the frozen inventory.
  • Additive Basics.round, floor, ceiling and truncate convert Float to Int32 with non-finite and overflow checks. Round resolves halves toward positive infinity: round -2.5 = -2.
  • Additive Decimal.div returns None for a zero divisor and Some quotient otherwise. Existing Decimal.divide still returns decimal and retains its existing zero-divisor exception behavior. Exact terminating Decimal96 division is covered; nonterminating or unrepresentable results are separate exclusions.

Already compiled inline calls can retain their old arithmetic, union or formatting behavior. Recompile consumers to use corrected inline bodies. Installing the canonical runtime alone preserves their type loading; it cannot replace code embedded in another assembly.

Features

  • Type Aliases: Morphir types mapped to idiomatic F# types (e.g., Maybe<'a> = Option<'a>)
  • Standard Library: F# SDK functions; the shared contract defines the bounded conformance inventory
  • Immutable Collections: Dict (Map), Set, List operations
  • Date/Time Support: LocalDate (DateOnly), LocalTime (TimeOnly)
  • AOT Compatible: No reflection, ready for Native AOT compilation

Modules

Core Types

  • Basics: Fundamental operations (Order type, comparison, arithmetic)
  • Maybe: Optional values (Option<'a> alias with helper functions)
  • Result: Error handling (Result<'v, 'e> with combinators)

Collections

  • List: List operations and extensions
  • Dict: Immutable dictionaries (Map<'k, 'v> alias)
  • Set: Set operations
  • Tuple: Tuple helper functions

Primitives

  • String: String manipulation functions
  • Int: Integer operations
  • Bool: Boolean logic
  • Char: Character operations
  • Decimal: Decimal arithmetic

Date/Time

  • LocalDate: Date without timezone (DateOnly alias)
  • LocalTime: Time without timezone (TimeOnly alias)

Usage Examples

Maybe (Option)

open Morphir.SDK

let user = { name = "Alice"; email = Some "alice@example.com" }

let emailDomain =
    user.email
    |> Maybe.map (String.split "@")
    |> Maybe.andThen List.last
    |> Maybe.withDefault "unknown"

Result

open Morphir.SDK

let validateAge age =
    if age < 0 then
        Result.err "Age cannot be negative"
    elif age > 150 then
        Result.err "Age is too high"
    else
        Result.ok age

let processAge =
    validateAge 25
    |> Result.map (fun age -> age + 1)
    |> Result.withDefault 0

List

open Morphir.SDK

let numbers = [1; 2; 3; 4; 5]

let result =
    numbers
    |> List.map (fun x -> x * 2)
    |> List.filter (fun x -> x > 5)
    |> List.sum
// result = 18

Dict

open Morphir.SDK

let scores =
    Dict.fromList [
        ("Alice", 95)
        ("Bob", 87)
        ("Charlie", 92)
    ]

let aliceScore = Dict.get "Alice" scores
// Some 95

let updatedScores = Dict.insert "David" 88 scores

LocalDate

open Morphir.SDK

let today = LocalDate.today()
let nextWeek = LocalDate.addDays 7 today
let formatted = LocalDate.toIsoString nextWeek
// "2025-01-07"

let parsed = LocalDate.fromIsoString "2025-12-31"
// Some (LocalDate(2025, 12, 31))

Relationship to morphir-elm

This library provides F# implementations of types and functions from morphir-elm's SDK. The API is designed to maintain semantic compatibility while leveraging F#'s native types and idioms.

Key Mappings

morphir-elm Morphir.SDK (F#) F# Native Type
Maybe a Maybe<'a> Option<'a>
Result e v F# Result<'v, 'e> Result<'v, 'e>
List a 'a list List<'a>
Dict k v Dict<'k, 'v> Map<'k, 'v>
Set a Set<'a> Set<'a>
LocalDate LocalDate DateOnly
LocalTime LocalTime TimeOnly

Design Principles

  1. Type Aliases Over Wrappers: Use F# built-in types directly when possible
  2. Zero-Cost Abstractions: No runtime overhead for type conversions
  3. Idiomatic F#: Follow F# conventions and naming patterns
  4. AOT Compatibility: No reflection or dynamic code generation
  5. Semantic Compatibility: Maintain morphir-elm behavior

Version Compatibility

  • Canonical package: Morphir.SDK.FSharp
  • Compatibility package: Morphir.SDK, at the matching version
  • .NET: 10.0+
  • F#: 9.0+
  • morphir-elm: Compatible with Morphir IR 2.x and 3.x

Contributing

This library is part of the morphir-dotnet project. For contributions, please see the main repository's CONTRIBUTING.md.

License

Apache License 2.0 - See LICENSE in the morphir-dotnet repository.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Morphir.SDK.FSharp:

Package Downloads
Morphir.SDK

Compatibility package for the Morphir F# runtime. Depends on Morphir.SDK.FSharp, which retains the Morphir.SDK namespace and runtime assembly identity.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.5.0-alpha.3 49 11/14/2026
0.5.0-alpha.2 46 11/13/2026
0.5.0-alpha.1 46 11/13/2026
0.4.0-alpha.5 48 11/13/2026
0.4.0-alpha.4 50 11/10/2026
0.4.0-alpha.3 58 11/9/2026
0.4.0-alpha.2 59 11/8/2026
0.4.0-alpha.1 57 11/7/2026

### Added

- Documentation: a getting-started walkthrough, [Your first model with morphirup](docs/content/docs/getting-started/first-model.md), and a [troubleshooting](docs/content/docs/getting-started/troubleshooting.md) page. The walkthrough installs `morphirup`, sets up the toolchain, compiles the `examples/morphirup-fsharp` model, generates F#, changes a rule and compares the output, then compiles and generates again offline. The getting-started pages now cover tasks only: the local candidate journey moves to the contributing section, implementation detail moves to the reference pages, and troubleshooting moves to the new page. The [morphirup](docs/content/docs/cli/morphirup.md) reference opens with a task section for `setup`, `show`, `select` and `run`, and `examples/morphirup-fsharp/README.md` repeats the walkthrough's commands.
- Install `morphirup` with one command. `scripts/install-morphirup.sh` (POSIX `sh`, Linux x64 and ARM64, macOS on Apple silicon) and `scripts/install-morphirup.ps1` (Windows x64 and ARM64, Windows PowerShell 5.1 and PowerShell 7) install the newest `finos/morphir-dotnet` release that has `morphirup` for the machine, prereleases included, or the release given with `--version` / `-Version`. Each script checks the file against the release's `morphirup-v<version>.sha256` and installs nothing on a mismatch or a missing line. The `sh` script installs to `~/.local/bin` and prints the `PATH` line to add; the PowerShell script installs to `%LOCALAPPDATA%/Programs/morphirup` and adds it to the user `PATH`. Intel macOS and musl Linux are refused. On restricted networks, both scripts use `HTTPS_PROXY` and `NO_PROXY` (the PowerShell script also uses the Windows proxy settings and the current user's proxy credentials, and passes `HTTPS_PROXY` itself on Windows PowerShell 5.1), accept an HTTPS mirror in `MORPHIRUP_DOWNLOAD_URL`, fall back to the release feed on github.com when api.github.com cannot be reached, and stop connecting after 30 seconds. The manually triggered workflow `install-scripts.yml` (inputs `version` and `platforms`) runs both scripts and the mise command `mise use -g 'github:finos/morphir-dotnet[matching=morphirup,version_prefix=v,prerelease=true]'` (also with `@<version>`) on Linux, macOS and Windows.
- Release setup on macOS ARM64: the release attaches the `osx-arm64` toolchain (the self-contained host archive, the F# frontend and backend archives with their release and manifest files, `morphir-host-candidate-osx-arm64.json`, `morphir-extensions-osx-arm64.json` and the bundle `morphir-toolchain-osx-arm64.json`), and its one `SHA256SUMS` covers win-x64, win-arm64 and osx-arm64. On Apple silicon, `morphirup setup --yes`, then `run -- compile` and `run -- generate --target fsharp`, work from the published release. The release job packs the toolchain on the native macOS ARM64 runner of `build-morphirup` and runs the acquired setup journey there; the pull request workflow does not, so its macOS job is unchanged. `WindowsToolchainChecksums` takes `--toolchain-platforms` for a run that packs only some toolchains.
- Experimental `morphirup` setup on macOS ARM64 (`osx-arm64`). `morphirup setup --local-developer` with a local candidate, host archive and bundle, then `select`, then `run -- compile` and `run -- generate --target fsharp`, works on Apple silicon with no .NET on `PATH` and no network. Release setup (`setup --yes`) accepts an `osx-arm64` manager and bundle too. Intel macOS stays unsupported.
- Build: `PackWindowsToolchain --rid osx-arm64` packs the macOS ARM64 setup inputs: tar.gz archives, the entry points `morphir`, `morphir-fsharp-frontend` and `morphir-fsharp-backend`, and the candidate, selection, release descriptors, manifests, bundle and `SHA256SUMS`. The target keeps its name, and the Windows outputs are unchanged.
- `Morphir.Extensions.Installation` installs tar.gz extension packages by the package policy of ZIP packages: at most 4096 entries (for tar, PAX/GNU metadata headers count too), only regular files and directories, the same package path rules (a `./` prefix, as `tar -C dir -czf package.tar.gz .` writes, is removed), the same size bounds, no inspection of a resource as a nested archive, and the canonical modes 0555 and 0444. Before, it refused them with `package.format_not_implemented`. A package format other than `zip` or `tar.gz` is refused with `package.archive_format` before staging.

### Changed

- The README and the installation guide start with `morphirup`: the install scripts, mise, manual download with checksum verification, and what works on each platform: macOS on Apple silicon and Windows set up, compile and generate; on Linux `morphirup` installs, but `morphirup setup` does not support Linux yet. Troubleshooting moves to its own page. The proto, `install-*.sh` and `dotnet tool install` routes to the standalone `morphir` CLI follow under "Other ways to install the standalone morphir CLI". The duplicate page `docs/content/getting-started/installation.md` is gone; its address redirects to the installation guide.
- The composed local-toolchains family moves from `0.1.0-preview.3` to `0.1.0-preview.4` ([finos/morphir#1164](https://github.com/finos/morphir/pull/1164), merged as `648ae374`; [spec](https://github.com/finos/morphir/blob/main/docs/spec/toolchain/local-platforms-and-release-bundle.md)), for every platform. Preview.4 adds `osx-arm64` with the archive format `tar-gzip`. The producer writes preview.4, and `morphirup` reads preview.4 only: candidates, bundles, receipts, selections and generations of preview.3 (written by 0.4.0-alpha.5 and earlier) are not read and are not converted. `select`, `show` and `run` read only the preview.4 selection pointer: in a Home set up with preview.2 or preview.3 they refuse with `local.setup_required`, which says to run `morphirup setup --yes` again (and then `select`, for a local candidate). Setup in that Home installs preview.4 beside the earlier generations without reading them, and replaces the selection pointer. The historical preview.1 local route is unchanged. The candidate reader refuses an `osx-arm64` candidate that does not declare `tar-gzip`, and a Windows candidate that does not declare `zip`. Setup and run refuse an `osx-arm64` entry point that is not `morphir` with `local.launch_structure` when they check the archive or the installed folder.
- `morphirup` off Windows uses the physical path of the parent folders of `--home`, with each link resolved (at most 40). The installed host refuses a source file below a link, and on macOS `$TMPDIR` is below the link `/var`. The last part is not followed, so a Home that is itself a link is still refused.
- `morphirup run` and the setup probes also remove `DOTNET_ROOT_ARM64` from the host's environment.
- A refused `morphirup setup`, `select` or `show` writes a local-toolchains `0.1.0-preview.4` result, on the preview.1 local route too. Before, every refusal except the composed local setup's wrote the preview.1 result with `origin: local-developer`. The `origin` is now the origin of the preview.4 generation that `select` names or of the selection that `show` reads, and `local-developer` when there is none. A completed preview.1 step still writes the preview.1 result.

### Fixed

- `morphir ir verify` no longer runs without end on a typical IR file. Each union branch of the schema checked its whole subtree even when the tag was another branch's, so the time grew exponentially with nesting. The `greeting-example.json` IR v3 example of finos/morphir (29 KB) ran for more than ten minutes and now takes under a second. The 3.5 MB LCR example takes about 20 seconds. A value with an unknown tag still lists the tags that were expected. For a value with a known tag, the deep errors of the other branches are gone: each other branch reports only that its tag does not match.
- `morphir ir verify` accepts IR v3 whose values carry their inferred types as attributes, as morphir-elm writes them, and names with a word that is a number. Both come from the current finos/morphir v3 schema. Before, the greeting example was not valid.
- `morphir ir verify` reads IR nested up to 512 levels. Before, a file deeper than 64 levels, such as the LCR example of finos/morphir, was reported as malformed JSON.
- `morphir` (and so `morphirup run -- compile` and `run -- generate`) no longer writes `[INF] Foundatio.Mediator registered 3 handler(s) and 0 middleware.` to stderr. The CLI logger caps the `Foundatio.Mediator` category at Warning, so the mediator's warnings and errors are still shown. Stdout is unchanged.
- Build: restoring the solution no longer rewrites the committed `packages.lock.json` of the `Morphir.Configuration.IO.Smoke` and `Morphir.Configuration.Microsoft.Smoke` hosts with the host's RID, so release artifacts built on Linux or Windows no longer record a dirty origin. A trimmed publish of these hosts passes `-p:PublishTrimmed=true`, and CI fails when restore changes the working tree.
- On Linux and macOS, an extension installation lock is free as soon as its owner releases it. Before, the lock stayed held while another thread of the same process was starting a child process, because that child shared the lock's file until it ran its program. A second extension operation in that window could fail with "Lease is busy".
- Extension installation works on Linux ARM64. Before, every operation on the extension Home there failed with `Cannot access '…/.morphir': native error 22.`: installing and registering extensions, reading the installed state, and `morphirup` downloads. The safe file layer passed the Linux x64 values of `O_DIRECTORY` and `O_NOFOLLOW`, which on ARM64 mean `O_DIRECT` and `O_LARGEFILE`, so it also did not refuse a symbolic link there. It now takes its open flags from a table for Linux x64, Linux ARM64 and macOS.