Morphir.Mep 0.5.0-alpha.5

Prefix Reserved
This is a prerelease version of Morphir.Mep.
dotnet add package Morphir.Mep --version 0.5.0-alpha.5
                    
NuGet\Install-Package Morphir.Mep -Version 0.5.0-alpha.5
                    
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.Mep" Version="0.5.0-alpha.5" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Morphir.Mep" Version="0.5.0-alpha.5" />
                    
Directory.Packages.props
<PackageReference Include="Morphir.Mep" />
                    
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.Mep --version 0.5.0-alpha.5
                    
#r "nuget: Morphir.Mep, 0.5.0-alpha.5"
                    
#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.Mep@0.5.0-alpha.5
                    
#: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.Mep&version=0.5.0-alpha.5&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Morphir.Mep&version=0.5.0-alpha.5&prerelease
                    
Install as a Cake Tool

Morphir.Mep

The Morphir Extension Protocol SDK for morphir-dotnet hosts and guests provides JSON-RPC 2.0 messages, Content-Length framing, the session lifecycle and model transport on MEP 0.2.0-draft.1. Bounded generation is an explicit opt-in to MEP 0.2.0-draft.2. The core SDK is tracked by #512 and add-mep-core. The roadmap is the Morphir extension model PRD, step 1.

Layers

Layer File What it does
Wire types Wire.fs Records and unions of the pinned contract, with parsed values (ProtocolVersion, SemanticVersion, Sha256Digest, RequestId). MepJson is generated from this file at build time by Morphir.Myriad.SystemTextJson. There is no reflection serializer.
Model transport ModelTransport.fs Tuple selection, the host check of a selection, envelope creation and admission. Pure functions.
Bounded generation ModelAccess.fs Complete tuple selection, start admission and the per-connection operation and round ledger.
Message codec Rpc.fs Classifies a JSON-RPC message by its members (JsonRpcMessage), keeps params raw, and writes messages. This is the only hand-written JSON.
Dispatcher Dispatcher.fs DispatchAsync(bytes, ct) returns the reply bytes, or none for a notification. A method table maps method names to typed handlers; a gate refuses a method before its handler runs.
Framing Framing.fs Content-Length frames on a Stream: header blocks up to 8192 bytes, bodies up to 64 MiB, checked before the body is read. A refused frame ends the connection.
Connection Connection.fs Reads frames, dispatches inbound requests concurrently, matches inbound responses to the pending-request table, and sends and receives $/cancelRequest.
Session Session.fs The pure lifecycle rules (Lifecycle.admit) and version negotiation, shared by hosts and guests.
Channel Channel.fs How a host session reaches its guest: a framed stream pair, or ISingleMessageChannel for a guest that takes one message per call. SessionFailure says why a single-message session ended.
Peers Peers.fs Guest (lifecycle methods, gate, extension methods) and HostSession (refuses to send what the guest must refuse).

On the guest side, the stream path (Connection) and the single-message path (Dispatcher.DispatchAsync) use the same dispatcher, so they give the same bytes. On the host side, HostSession holds a channel and applies the same lifecycle, version and model-transport rules on either. Starting a guest process is not in this project: a process host connects a HostSession to the child's streams.

Channels

A host session sends a request and waits for its reply, and sends notifications. It does both through a channel (CHAN-1). HostSession checks each request against the lifecycle state before it uses the channel, so a request refused on one channel is refused on the other with the same error, and the guest never receives it.

Channel Constructor What the guest is
Framed stream pair HostSession(input, output, host, offer) A process with Content-Length frames on its standard streams. Requests run concurrently and are matched by id; a cancelled request sends $/cancelRequest; the guest can send morphir.progress.
Single message HostSession(channel, host, offer) A guest that takes one whole message per call, such as the handle export of a WASM guest. The runtime implements ISingleMessageChannel; tests/Morphir.Mep.AotProbe has a C# implementation.

ISingleMessageChannel has two members. Both take the method name, the bytes of one complete UTF-8 JSON-RPC message with no Content-Length header, and a cancellation token. Both return the bytes of the message the guest returned, or null when it returned none.

  • RequestAsync calls the guest with a request.
  • NotifyAsync calls the guest with a notification, or withholds it when the guest's runtime does not deliver notifications to that guest. A withheld notification does not call the guest. HostSession always sends morphir.initialized and morphir.exit; the runtime decides whether the guest receives them.

The implementation passes bytes and does not check them. HostSession applies these rules to a single-message guest:

  • One call at a time. A request waits until no other call is inside the guest.
  • A request takes exactly one reply: the response or error response with the request's id. No bytes, a response for another id, a request or notification (such as morphir.progress), bytes that are not a JSON-RPC message, or a reply over ContentLengthFraming.MaxBodyBytes fail the session.
  • A notification takes no reply. Bytes returned for one fail the session.
  • The host never sends $/cancelRequest. When a request's token is cancelled, the channel stops the call and ends it with OperationCanceledException. The request ends with -32800 and the session ends.
  • An exception from the channel fails the session.
  • After the session fails, no message reaches the guest. Failure (C#: FailureOrNull()) says why, as a SessionFailure. The request that failed gets -32800 when it was cancelled and -32603 otherwise. Later requests get -32603 without a call. A failure during InitializeAsync gives InitializeFailure.Refused with that error. RunAsync ends with Stopped at exit or failure.

Which notifications a WASM guest accepts is read from its morphir.initialize result by the runtime, not by HostSession. The member that advertises it is not fixed in the contract yet (NTFY-1).

A guest and a host in memory

This example is compiled by tests/Morphir.Mep.Tests/ReadmeTests.fs. Keep the two equal.

let runSession (claims: CapabilityClaimSet) (capabilities: ExtensionCapabilities) =
    task {
        let guest =
            Guest(
                { Claims = claims
                  Capabilities = capabilities
                  Methods = readOnlyDict [] }
            )

        let toGuest = Pipe()
        let toHost = Pipe()
        let guestRun = guest.RunAsync(toGuest.Reader.AsStream(), toHost.Writer.AsStream(), CancellationToken.None)

        let host =
            HostSession(
                toHost.Reader.AsStream(),
                toGuest.Writer.AsStream(),
                { Kind = PeerKind.Cli; Name = "morphir"; Version = "0.4.0" },
                null
            )

        let hostRun = host.RunAsync CancellationToken.None
        let! session = host.InitializeAsync CancellationToken.None
        let! ping = host.PingAsync CancellationToken.None
        let! _ = host.ShutdownAsync CancellationToken.None
        do! host.ExitAsync()
        let! guestEnd = guestRun
        toHost.Writer.Complete()
        let! _ = hostRun
        return session, ping, guestEnd
    }

Bounded generation

An extension can generate from a package on disk without receiving the whole package at initialization. It asks for the inventory or documents it needs in each continuation. The host keeps the snapshot lease and answers from the same revision. The same exchange works on a framed process connection and a WASM byte-call channel.

sequenceDiagram
    participant Host
    participant Guest
    Host->>Guest: initialize with modelAccess
    Guest-->>Host: select draft.2 and complete tuples
    Host->>Guest: StartGenerationAsync with one tuple and snapshot
    Guest-->>Host: Continue round 1 with inventory requests
    Host->>Guest: AdvanceGenerationAsync with deliveries in request order
    Guest-->>Host: Continue with the next round, Complete, or Failed

Construct the host with HostSession.CreateWithModelAccess, supplying ModelAccessSupport and an optional legacy transport offer. The guest lists draft.2 in Claims.ProtocolVersions and declares Capabilities.ModelAccess, its backend targets and its start, advance and cancel handlers. Check the selected draft and tuple in InitializeAsync before choosing the request's input. A draft.1 selection keeps the existing whole-model path.

For example, when a continuation has no requests, the host advances with an empty delivery list. This example is compiled by ReadmeTests.fs.

let advanceEmpty (host: HostSession) (step: ModelAccessStep) cancellation =
    match step with
    | ModelAccessStep.Continue(id, round, requests, _, _) when requests.Count = 0 ->
        Some(host.AdvanceGenerationAsync({ SessionId = id; Round = round; Deliveries = [||] }, cancellation))
    | _ -> None

For a nonempty continuation, supply one delivery per request in order. CancelGenerationAsync requests release of an open operation and checks the acknowledged ID. An invalid round does not consume the outstanding round. Completion, failure and an acknowledged cancel retire the operation ID for the connection. Both peers check exchange identity and order. Before passing a document delivery to the transport or handler, they verify canonical base64, decoded length, and SHA-256. They enforce the batch document count and the aggregate encoded and decoded byte ceilings before decoding. An invalid delivery leaves the pending round available for correction. Snapshot access, IR decoding, execution deadlines, artifact staging, and publication belong to the host and extension operating the session. See the bounded-generation contract for the complete exchange and resource limits.

Add a method

  1. Check that the pinned contract has the method and its params and result types. Do not add a method, member or error code that the pin does not have; raise an upstream issue.
  2. Write a failing wire test, then add the types to Wire.fs with the attributes that the contract's wire rules need. Add the type to the contract test (ContractTests.fs): a complete sample, and the members that the contract text lets a reader default.
  3. Add the method to Method if it is new, and its capability to Lifecycle.capability if the contract makes it depend on one (the guest replies -32013 without it).
  4. Register a handler in the guest's Methods with Handlers.request (params bind as one object through their codec; absent or mismatched params give -32602), and add a typed call to HostSession if hosts send it.
  5. Add the method to the AOT probe (tests/Morphir.Mep.AotProbe) when it changes what C# calls.

The pin

tests/Fixtures/Mep pins the upstream contract model (mep.ir.json), the transcripts and the model-transport corpus by commit and digest. Do not edit the fixtures. To update the pin:

  1. Copy the new files from finos/morphir at one commit, and record the commit and the SHA-256 digests in PROVENANCE.md.
  2. Run the tests. ContractTests fails for each renamed or added member, and the transcript and corpus tests fail for each changed behavior.
  3. Change the types and rules in the same pull request. A new MEP version moves every MEP part in morphir-dotnet together; drafts match only exactly.

Where a transcript and the contract text disagree, the tests follow the contract text. The legacy transcripts initialize with 0.1; the replays use 0.2.0-draft.1 instead. The separately pinned bounded-generation transcript runs on exact draft.2.

C# callers

The project is trimmable and AOT-compatible, with F# nullness metadata. Parsed values have TryParse and Create; FrameRead and SessionFailure have Match. tests/Morphir.Mep.AotProbe is a C# consumer that runs the full session on streams and on a C# ISingleMessageChannel; InteropTests and ChannelTests compile C# examples and check the nullable-flow diagnostics.

Tests

dotnet run --project tests/Morphir.Mep.Tests -- --summary
./build.sh --target TestAot --configuration Release

The first command runs the wire, contract, JSON-RPC, connection, session, channel and model-transport tests in memory. The channel tests use a fake single-message guest built on Dispatcher.DispatchAsync. The second is the Native AOT lane of the black-box tests: it publishes the probe (and the other probes and library hosts) with Native AOT, refuses IL diagnostics other than the FSharp.Core summary baseline, and compares the native output with the managed output. Both run in PR CI.

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 (4)

Showing the top 4 NuGet packages that depend on Morphir.Mep:

Package Downloads
Morphir.Extensions

Morphir extension registry domain: parsed extension identities, capability claims and the extension catalog

Morphir.Compilation.Mep

The MEP 0.2.0-draft.1 host side of guest processes: the guest process and session, and the frontend adapter, an IFrontend over a guest that serves morphir.frontend.compileModel. Trim-safe and AOT-safe.

Morphir.Extensions.Installation

Local extension package installation, inventory, selection and activation for Morphir tooling.

Morphir.Extensions.Wasm

The WASM extension runtime of morphir-dotnet: Wasmtime with the embedded Extism kernel module.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.5.0-alpha.5 50 11/22/2026
0.5.0-alpha.4 89 11/16/2026
0.5.0-alpha.3 97 11/14/2026
0.5.0-alpha.2 96 11/13/2026
0.5.0-alpha.1 94 11/13/2026
0.4.0-alpha.5 98 11/13/2026
0.4.0-alpha.4 82 11/10/2026
0.4.0-alpha.3 79 11/9/2026

### Added

- `Morphir.Svg` builds immutable SVG scenes with F# computation expressions and C# factories. `Morphir.Diagrams` reads Mermaid flowcharts and sequence diagrams and renders standalone SVG or an offline HTML player in a theme with dark and light palettes: Archify (the default), Monokai, Cobalt, Solarized, Gruvbox, Ocean, Darcula, Material or a custom `DiagramTheme`. `SvgRenderOptions` selects the theme and a mode: `Auto` follows the viewer preference, and `Dark` or `Light` writes one palette. The colours are documented CSS variables that a host page can override. See the [diagram library guide](src/Morphir.Diagrams/README.md) for current coverage.
- `Morphir.Knowledge` provides versioned text selections, annotations and links. `Morphir.Knowledge.Okf` provides an AST and lossless CST with cursor visitors and OKF v0.2 and v0.3 bundle validation through `morphir knowledge validate`. `Morphir.Knowledge.Rdf` provides RDF datasets, graph and statement addresses, and N-Quads exchange. See the [knowledge library guide](src/Morphir.Knowledge/README.md).
- Diagram-linked metadata. Every element of a Mermaid diagram has a stable reference (`DiagramElementRef`, such as `node=Billing` or `edge=Cart/Billing/0`) and an IRI under the diagram's document, and rendered SVG marks each element with `data-ref`. `DiagramSnapshot` and `DiagramSelection` target elements of one source revision, which defaults to the SHA-256 of the source. `DiagramAnnotations` maps comments (W3C Web Annotation) and links to text, code, IRIs or other diagrams to and from RDF, and keeps every other statement. `SvgRenderOptions.WithDocument` and `WithMetadata` embed a dataset canonically in the SVG's `metadata` element as RDF/XML, N-Quads or N-Triples, `DiagramMetadata.TryRead` reads it back, and the offline player marks each annotated element and lists its comments, links and statements in a notes panel. `Morphir.Knowledge.Rdf` adds N-Triples and RDF/XML reading and writing (the W3C RDF/XML suite passes) and RDFC-1.0 canonicalization (the W3C rdf-canon suite passes); `Morphir.Svg` adds namespaced names and a secure metadata reader. XML readers prohibit DTDs and use no resolver. See [Metadata in the SVG](src/Morphir.Diagrams/README.md#metadata-in-the-svg) ([#689](https://github.com/finos/morphir-dotnet/issues/689))
- Every diagram family of diagrams.mbt 60a8dd1. `Morphir.Diagrams` reads Mermaid state, swimlane, architecture (with 526 icon keys: AWS, Azure, Google Cloud and UML symbols copied with their notices, and symbols drawn for this library) and ZenUML diagrams; PlantUML activity (modern and legacy), state, regex, EBNF, JSON and YAML blocks; and BPMN 2.0.2 process and collaboration views with BPMN notation, supplied geometry or an automatic layout. `DiagramSource` detects the language. Each family has element references, themes, the offline player and a printer where the syntax has one (`Mermaid.Print`, `PlantUml.Print`), and the pinned upstream corpora are read as Mermaid and PlantUML read them. Mermaid flowcharts and sequences gain the remaining syntax and canonical printing; connectors take elbow, rounded or curved styles and opt-in bridges; railroad diagrams draw external match traces; and the player explores routes and reachability (`DiagramExploration`) and plays node visits. See the [diagram library guide](src/Morphir.Diagrams/README.md).
- `Morphir.Bpmn` reads BPMN 2.0.2 XML with DTDs and entities refused into a lossless tree and a typed element view, validates structure and references, writes canonical and pretty XML, and traverses and queries the document without recursion. `Morphir.Diagrams.Query` adds a bounded structural query language over trees with a BPMN adapter. `Morphir.Diagrams.Raster` exports the library's SVG as PNG or JPEG and a playback as an animated GIF in managed code, with the same bytes on every platform, embedded Noto fonts under the SIL Open Font License, and player downloads. See [Morphir.Bpmn](src/Morphir.Bpmn/README.md), [Morphir.Diagrams.Query](src/Morphir.Diagrams.Query/README.md) and [Morphir.Diagrams.Raster](src/Morphir.Diagrams.Raster/README.md).
- `DocumentTreeStore.openSnapshot` reads plain v3.1 and v4 JSON or YAML document trees from an `IFileProvider`. Generators can page modules and members and decode selected definitions within a per-file byte limit. The caller keeps the input revision stable while those operations run. See [the pipeline guide](src/Morphir.IR.Pipeline/README.md#read-a-document-tree-by-page).
- The bounded document-tree reader reads contextual trees too: it resolves a name-compaction alias in one typed slot without expanding the enclosing body, in JSON and YAML, and keeps the original bytes for pass-through. It can export one logical file as expanded plain JSON under an output limit that is separate from the source limit, without holding every definition body, and keeps the physical stems that `fileNames` records ([#681](https://github.com/finos/morphir-dotnet/pull/681), [#684](https://github.com/finos/morphir-dotnet/pull/684)).
- `Morphir.Mep` negotiates MEP `0.2.0-draft.2` with model access `0.1.0-draft.1`. A guest can generate from a package on disk without receiving the whole model: `HostSession.CreateWithModelAccess` builds the host, and `StartGenerationAsync`, `AdvanceGenerationAsync` and `CancelGenerationAsync` drive ordered rounds in which the guest requests inventory pages and documents of one snapshot. Deliveries are checked for canonical base64, length, SHA-256, request order and batch limits before dispatch. A draft.1 selection keeps the whole-model path. The same exchange runs on a framed process connection and on a WASM byte-call channel. See [Bounded generation](src/Morphir.Mep/README.md#bounded-generation) ([#680](https://github.com/finos/morphir-dotnet/pull/680), [#684](https://github.com/finos/morphir-dotnet/pull/684)).
- `morphir generate` without `--input` generates from a compile record whose IR is a document tree through a bounded session. The host offers the record's exact IR version and codec under MEP `0.2.0-draft.2`, holds the compile read lease until the guest has stopped, and serves the selected documents without giving the guest the tree's path. It works with a native guest (`--extension`) or an Extism WASM guest configured under `[extensions.<target>]` with `abi = "extism-kernel-v1"`. Frame, guest-state and artifact limits are checked before decoding, and one `maxSessionWorkUnits` budget covers reading and output; running out returns `extension.bounded_work_limit` and discards the stage. Chunks are staged privately, then the completed files go to `<out-dir>/generate/<target>.dest`, are recorded in `<target>.json` and are installed into `--output` through the task record's `installed` ledger. A run that fails after replacing a working result leaves a tombstone, and the previous install stays in place. See [Bounded generation from a compile record](docs/content/docs/cli/generate.md#bounded-generation-from-a-compile-record) ([#690](https://github.com/finos/morphir-dotnet/pull/690), [#691](https://github.com/finos/morphir-dotnet/pull/691), [#697](https://github.com/finos/morphir-dotnet/pull/697)).
- `morphir generate --bounded-profile orders-scale` selects provisional limits for the recorded-tree path with a configured WASM backend and a plain JSON v4 tree, for the Orders scale workload. Its JSON report adds `boundedAccess`: the effective limits, the guest's and Extism kernel's peak linear memory against the applied ceiling, the largest input and output batches, and the discovery index's peak charge. These limits are not a resident-memory guarantee. See [Manual Orders scale admission](docs/content/docs/cli/generate.md#manual-orders-scale-admission) ([#693](https://github.com/finos/morphir-dotnet/pull/693), [#696](https://github.com/finos/morphir-dotnet/pull/696)).
- `Morphir.Files` exchanges trees with `Microsoft.Extensions.FileProviders`: `VFileProviders.asFileProvider` gives a `VFileTree` wherever an `IFileProvider` is accepted, and `VFileProviders.ofFileProvider` builds a tree from any provider (physical, embedded, composite) without reading a file until it is read. `Morphir.Models` now depends on `Morphir.Files`, so the analyzer and MSBuild task folders of `Morphir.Lang.CSharp` also carry `Morphir.Files`, `Microsoft.Extensions.FileProviders.Abstractions` and `Microsoft.Extensions.Primitives`. See [the Morphir.Files README](src/Morphir.Files/README.md#exchange-files-with-ifileprovider).
- `Morphir.Models` has `Morphir.IR.Trees.TreeStems`, the stems of a document tree that `Morphir.Ion` used internally: `escapeName` writes a name as a file stem, `parseStem` reads one back (a whole name or a cut stem), `matchesCut` checks a cut stem's prefix and digest against a name, and `splitDependency` splits a `deps/` path at its bare `@` segment.
- `ClassicJsonWriter` writes a classic `Specs` distribution at format `3.1.0` with the new profile `ClassicWireProfile.v3_1_0`: `"formatVersion": "3.1.0"` and the `Specs` tag. A Specs at 1, 2 or 3, or a Library at 3.1.0, is refused with `unsupported-distribution`, and the message names the supported set. `Morphir.IR.Trees.ClassicDocumentTree`, beside `V4DocumentTree`, splits a classic v3 model into a document tree and joins it back with every attribute unchanged; its manifest records whether the single file says `3` (a Library) or `"3.1.0"` (a Specs).
- `morphir model verify` checks IR v4 and document trees. A single file with `"formatVersion": 4` (or a v4 release such as `"4.0.0"`) is checked against the parent's `morphir-ir-v4.json`, and `--schema-version=4` selects it; it is then decoded with the v4 reader, which names the node at fault in a module (the parent's schema, which checks a module in every spelling, locates the fault only at the module), and the reader's error is listed with its code and JSON location. A directory is a document tree: each file of a v4 tree against its kind in the parent's `morphir-ir-v4-document-tree-files.json`, then every rule of a tree and every document through the document-tree store, as `morphir model convert` reads it; a v3 tree, whose files say `"3.1.0"`, through the store alone. Every error is listed, each with its `file` in the tree and its JSON location (`Path`, a JSON Pointer), and a rule of the tree has the parent's code, such as `missing_member`. The version of a tree comes from its manifest, and a `--schema-version` that contradicts it exits 2 with `verify.schema_version_conflict`. The report adds `layout` (`single-file` or `document-tree`), `filesChecked` and `compactedFiles`, and an error of a tree adds `file` and `code`. See [model verify](docs/content/docs/cli/model-verify.md#document-trees).
- `morphir model convert` stores a Morphir model as a single file or as a document tree without changing the model or its IR version: `morphir model convert --input morphir-ir.json --output tree --layout=document-tree`, and back with `--layout=single-file`. The input's layout is detected (a file or a tree's directory), and `--layout=document-treesingle-file` chooses the output's (the form with a space is accepted too); it defaults to the input's layout, and a run that changes neither the layout nor the encoding exits 2 with `model.nothing_to_do`. IR v3 and IR v4 are converted: a v3 Library tree says `"3.1.0"` in every file and joins back to `"formatVersion": 3`, a v3 Specs keeps `"3.1.0"`, and a v1 or v2 file is refused with `model.unsupported_version`. A tree is read and written through the document-tree store that `model verify` checks trees with, so a refused tree has the parent's code, such as `missing_member` or `tree.ambiguous_profile`, and names its file; a v4 manifest's `version` and `created` are dropped with a `tree.dropped_manifest_member` notice each. `--output` must not exist (a tree may also go to an empty directory) and must not overlap the input (`model.output_not_empty`, `model.output_overlaps_input`); the output is staged beside it and moved into place, so a refused or failed run leaves nothing there. `--json[=streamdocument]` gives the report (`success`, `exitCode`, the paths, layouts and encodings, `irVersion`, `filesWritten`, `diagnostics`, `notices`) and, as a stream, `stageStarted`, `stageCompleted`, `diagnostics`, `notices` and one `fileWritten` event per file. Compacted files are read and written (see the next two entries). See [model convert](docs/content/docs/cli/model-convert.md).
- `morphir model convert` and `morphir model verify` read compacted Morphir files: a single file or a tree file in a name-compaction envelope of finos/morphir's `ir/name-compaction` (`ir-context` 0.1.0-draft.1), whose document names entries of the envelope's `context` with `{"$name": "<id>"}`. The document is expanded at the typed name positions only (classic word arrays in a v3 document, canonical strings in a v4 one, with no change of version), and then read or checked as a plain document. `convert` writes the expanded model plain and states `inputEncoding: "compacted"`; a tree is compacted when any of its files is, so a compacted input with no `--layout` is not `model.nothing_to_do`. `verify` checks the expanded documents against their schemas and lists the compacted files in `compactedFiles`. An envelope or a context that breaks a rule of the contract is refused, naming the file, with the contract's code: `context.undeclared_schema`, `context.unknown_alias`, `context.duplicate_entry`, `context.unknown_critical`, `context.too_many_entries`, `context.name_too_long`, `context.after_document`, `context.invalid_envelope` or `context.invalid_entry` (exit code 1). See [Encodings](docs/content/docs/cli/model-convert.md#encodings) and [Compacted files](docs/content/docs/cli/model-verify.md#compacted-files).
- `morphir model convert --compact[=names]` writes compacted files under finos/morphir's writer policy `morphir.compact/0.1.0-draft.1`: a single file stays one file, and each file of a tree, the manifest included, gets its own context. A name, path or fully qualified name gets an alias only when its uses save more bytes than its table entry costs, and the envelope is written only when the aliases save more than it adds; otherwise the file is its plain document, with a `model.compaction_declined` notice. Every file written with `--compact`, compacted or declined, is in the policy's written form: the member sorting and string escaping of RFC 8785 canonical JSON, no whitespace and no trailing newline, with three exceptions: numbers are written as the plain file writes them (IR v4 keeps their lexemes, so `9007199254740993`, `1.0` and `1e2` stay as they are; a classic v3 float is a double, which the plain file writes in its shortest form, so `1.0` and `1e2` are written `1` and `100`, compacted or not, with the same value), the parameters of a v4 value (a definition's `inputTypes`, a specification's `inputs`) keep their order, and the content of a `DocumentLiteral` is written exactly as in the source, its keys in their order and its numbers as their lexemes. Every size is the UTF-8 byte length of that form. Record fields, module members, constructors and dependencies may come back in sorted order; function parameters keep their order. `Morphir.Json.CanonicalJson.writeSourceForm` writes that form, and `CanonicalJson.write` stays RFC 8785. On Windows, the move of the written output into place, a single file or the staged directory of a tree, waits a bounded time while another process briefly holds a written file open (`Morphir.Files.FileReplacement`, which also counts the access denial that `Directory.Move` raises as an `IOException`), as the publication of a tree's files does; if something appears at the output during the wait, the write is refused with `model.write_failed` and that output is left as it is, never replaced or merged into. The output equals the policy's fixed cases byte for byte, expands to the document it was written from, and is the same for the same model. The report names `compactMode` and `compactPolicy`, and `outputEncoding` is `compacted` when a file written is in an envelope. In `Morphir.Models`, `Morphir.IR.Files.CompactionPolicy.compact` compacts one document, `DocumentTreeStore.write` with `Compact = Some Names` compacts each file of a tree and lists the declined ones in `DocumentTreeStore.plainFiles`, and `StoredModel.TryWriteSingleFile` takes the compaction flag and says whether an alias was worth its cost. See [Compaction](docs/content/docs/cli/model-convert.md#compaction).

### Changed

- `morphir model verify` refuses a single file whose top-level `$schema` is not the declared name-compaction envelope (`ir-context` 0.1.0-draft.1) with `context.undeclared_schema` (exit code 1). It used to check such a file as a plain document. An error in a compacted file is located in the file as written: its `Path` starts with `/document`, the envelope's document member.
- `morphir model verify` lists only the errors of the subschemas that fail: an error of a branch of an `anyOf` or a `oneOf` that another branch satisfies is no longer listed, so an invalid node no longer brings errors of members that are valid. `--schema-version` takes 1 to 4, and another number is a usage error with exit code 2, where it was reported as a file that does not exist. A path whose directory does not exist is reported as a file that does not exist rather than failing.
- **BREAKING:** `morphir model` replaces `morphir ir`. The group holds the commands that act on a Morphir model, and `morphir ir verify` is now `morphir model verify`, with the same inputs, options and exit codes, apart from the changes below and the `--schema-version` entry above. There is no alias: `morphir ir` is an unknown command, so scripts change `ir verify` to `model verify`. The verification report adds `exitCode` (0 valid, 1 not valid, 2 a command line that does not parse) beside `IsValid`, which keeps its name, so the report itself tells a usage failure from a model that is not valid. `--quiet` with a JSON mode now writes the JSON report, which it hid before; `--quiet` alone still writes nothing. See [model verify](docs/content/docs/cli/model-verify.md).
- **BREAKING:** `ClassicWireProfile` replaces `LibraryTag` with `Distribution` (`ClassicProfileDistribution.Library` or `ClassicProfileDistribution.Specs`, each with its tag) and adds `Release`, the string `formatVersion` of a release profile, and `EntryDocs`, how a type or value of a module with no documentation is written. The v1, v2 and v3 profiles write the same bytes as before.
- **BREAKING:** `morphir compile --json` streams: it writes the compile events as JSON Lines (`stageStarted`, `diagnostics`, `stageCompleted`) and ends with one `{"event":"completed","report":{...}}` record that holds the report. `--json=document` writes the report alone, as `--json` did before. `--json-lines` is removed and fails as an unknown option with exit code 2; use `--json`. A mode is given only after `=`: `--json document` fails with exit code 2 and suggests `--json=document`, and the help shows `--json[=streamdocument]`. The conformance `cli` adapter drives `compile --json`.
- **BREAKING:** every other command with machine output follows the same convention: `validate`, `generate`, `config` (`get`, `list`, `show`, `path`, `explain`, `set`, `unset`), `extension list`, `extension runtimes`, `project migrate`, `workspace migrate` and `model verify`. A bare `--json` now writes one `{"event":"completed","report":{...}}` line, which is also one JSON document; `--json=document` writes the report alone, as `--json` did before. A mode is given only after `=`, so `model verify --json model.json` verifies `model.json`, and a mode that is not `stream` or `document` fails with exit code 2. A parse or usage error in a JSON mode still ends with one report and exit code 2: `extension list`, `extension runtimes` and `model verify` now render their own parse errors, with exit code 2 instead of 1. The usage failure of `config` and the migrations adds only the parser messages that quote no value (an unknown mode, the `--json=document` hint, an unknown option name). `extension worker` keeps the form of the pinned WASM worker contract: `--help --json` still writes one `morphir/command-result`, with no `completed` wrapper, and the event lines stay `morphir/command-event`; it takes `--json=stream` and `--json=document`, which change nothing. The conformance runner refuses a host whose help result is wrapped. morphirup's readiness check runs `generate --json=document`. See [Machine output](docs/content/docs/cli/_index.md#machine-output).
- `VFile`, `VFileTree` and `PropertyBag` moved from `Morphir.IR.Pipeline` to the new package `Morphir.Files`, in the namespace `Morphir.Files`. Code that uses them adds `open Morphir.Files` (F#) or `using Morphir.Files;` (C#). `Morphir.IR.Pipeline` depends on `Morphir.Files` and keeps `MorphirProcessor`, so a pipeline also opens `Morphir.IR.Pipeline`.
- `Morphir.Files` writes the nullable metadata of F# nullness, as `Morphir.Models` does, so C# sees which of its values may be null: the delegates of `FileReplacement.Replace` must not be null, and `PropertyBag.Equals` accepts `null`. Before, C# saw every reference type of the package as oblivious and gave no warning for a `null` argument.

### Fixed

- `morphir generate --input <directory>` checks the captured files a second time before decoding. If a file changed or disappeared during capture, it stops with `input-changed` before starting the backend; before, it could generate from a mix of old and new files ([#698](https://github.com/finos/morphir-dotnet/pull/698)).
- `morphir model verify` reports `tree.unreadable_file` with the file name when a document-tree stream fails on close.
- `morphir model convert` no longer drops a member of a classic v3 model that the classic model has no place for, such as a member beside the `inputTypes`, `outputType` and `body` of a value definition, at any depth of a v3 single file or of the `def` or `spec` of a v3 tree file, including a member beside the `access` and `value` of a `def` or the `doc` and `value` of a documented entry (which a tree read refused as `invalid_distribution_shape` at the payload). It refuses the input with `unknown_member` at the member's JSON location (exit code 1, nothing written), and `morphir model verify` reports the same error for a v3 tree, and for a v3 single file that states `"formatVersion": 3` or `"3.1.0"`, which it now also reads with that reader after the schema check. In `Morphir.Models`, `ClassicJson.readDistributionStrict` reads as `readDistribution` does and refuses such a member; `StoredModel.TryReadSingleFile` and the v3 tree reader use it. See [Layouts](docs/content/docs/cli/model-convert.md#layouts).
- `morphir model verify` accepts the v3 `Specs` single file that `morphir model convert` writes. A single file that says `"formatVersion": "3.1.0"` is checked against finos/morphir's 3.1.0 schema (`morphir-ir-v3.json` at `4fa51c8b`, pinned as `morphir-ir-v3.1.0.json`), also with `--schema-version=3`, where the older v3 schema, which accepts the integer `3` and a `Library` only, refused it; the report still says schema version `3`. To pass that schema, `ClassicWireProfile.v3_1_0` writes each type and value of a module that has no documentation as `{ "doc": null, "value": ... }`, the wrapper the 3.1.0 schema requires, where it wrote the bare entry; the new `ClassicWireProfile.EntryDocs` (`ClassicEntryDocStyle.Bare` or `NullDoc`) holds the choice, and the integer 3 profile writes the same bytes as before. See [Schema version detection](docs/content/docs/cli/model-verify.md#schema-version-detection).
- `morphir model convert` writes a document tree that it can read back when a module has a type and a value of one name whose path is over the path budget. Their files now share one cut stem, short enough for the longer `.value.json` path, and the module file's `fileNames` names the name once; before, each file got its own cut stem, `fileNames` held the name twice, and reading the tree failed with `duplicate_member` and `tree.name_mismatch`. finos/morphir's tree specification maps a name to one stem in `fileNames` and does not say how a shared name is cut.
- `ProjectPath.join` keeps an absolute Windows path written with backslashes. `morphir project migrate C:/work/orders` and `config --file C:/work/morphir.toml` no longer read the path as relative to the invocation directory (which `project migrate` reported as `migration.io`).