From a329379bfae4122a2917138286891b4cac6b2ead Mon Sep 17 00:00:00 2001
From: Damian Reeves <957246+DamianReeves@users.noreply.github.com>
Date: Tue, 27 Oct 2026 20:12:01 -0500
Subject: [PATCH 1/3] docs(openspec): propose write-compact-ir-v4

The writer half of morphir-ukvn.8.16: write the compact canonical v4
spelling the profile prefers, flatten documentation per decision 0010,
and keep the expanded spelling selectable.
---
 .../write-compact-ir-v4/.openspec.yaml        |  2 +
 .../changes/write-compact-ir-v4/design.html   | 67 +++++++++++++++++++
 .../changes/write-compact-ir-v4/proposal.md   | 31 +++++++++
 .../write-compact-ir-v4/specs/ir/v4/spec.md   | 32 +++++++++
 .../specs/tools/ir-interchange/spec.md        | 14 ++++
 openspec/changes/write-compact-ir-v4/tasks.md |  9 +++
 6 files changed, 155 insertions(+)
 create mode 100644 openspec/changes/write-compact-ir-v4/.openspec.yaml
 create mode 100644 openspec/changes/write-compact-ir-v4/design.html
 create mode 100644 openspec/changes/write-compact-ir-v4/proposal.md
 create mode 100644 openspec/changes/write-compact-ir-v4/specs/ir/v4/spec.md
 create mode 100644 openspec/changes/write-compact-ir-v4/specs/tools/ir-interchange/spec.md
 create mode 100644 openspec/changes/write-compact-ir-v4/tasks.md

diff --git a/openspec/changes/write-compact-ir-v4/.openspec.yaml b/openspec/changes/write-compact-ir-v4/.openspec.yaml
new file mode 100644
index 00000000..dda53b8a
--- /dev/null
+++ b/openspec/changes/write-compact-ir-v4/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: html-design
+created: 2026-10-27
diff --git a/openspec/changes/write-compact-ir-v4/design.html b/openspec/changes/write-compact-ir-v4/design.html
new file mode 100644
index 00000000..a8cf8ead
--- /dev/null
+++ b/openspec/changes/write-compact-ir-v4/design.html
@@ -0,0 +1,67 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>write-compact-ir-v4: design</title>
+<!--
+  Agent document template (docs/templates/agent-document.html). Specs, plans and reports that a person reviews
+  start from this file: copy it, keep the <head> as it is, and write the content inside <main>
+<h1>write-compact-ir-v4</h1>
+<p class="meta">OpenSpec change write-compact-ir-v4 · Bead morphir-ukvn.8.16 · 2026-10-27 · Proposed</p>
+
+<nav class="toc" aria-label="Contents">
+<ul>
+<li><a href="#context">Context</a></li>
+<li><a href="#goals">Goals and non-goals</a></li>
+<li><a href="#decisions">Decisions</a></li>
+<li><a href="#risks">Risks and trade-offs</a></li>
+<li><a href="#migration">Migration and rollback</a></li>
+</ul>
+</nav>
+
+<h2 id="context">Context</h2>
+<p>See proposal.md, Why. The v4 reader already accepts every spelling the pinned schema allows. The writer builds each node in <code>packages/morphir/src/morphir/ir/v4/codec.py</code> with <code>_wrap(tag, _with_attributes(attrs, members))</code>, recursing through about 50 call sites that thread only a location. morphir-core 0.2.0 is the reference writer at the same profile: it chooses compact or expanded per node from a thread-local encoding and writes <code>doc</code> flattened and first.</p>
+<p>Encoding the morphir-core output of the compiler fixtures with the current Python writer differs only in the node shapes listed in the proposal: type references, tuples, literals, variables and references.</p>
+
+<h2 id="goals">Goals and non-goals</h2>
+<p>The default output of a model must equal morphir-core's output for the same model, byte for byte, including member order. Nothing in the decoded model may change. Not covered: field order in records or maps beyond what the model holds, number lexemes that Python's <code>json</code> does not keep, and the deferred re-sync items listed in the proposal.</p>
+
+<h2 id="decisions">Decisions</h2>
+<h3>CDC-1. Select the spelling per public call with a context variable</h3>
+<p>A <code>Spelling</code> enum (<code>COMPACT</code>, <code>EXPANDED</code>) is held in a <code>contextvars.ContextVar</code> that defaults to <code>COMPACT</code>. Public encoders take a keyword-only <code>spelling: Spelling | None = None</code>. They set the variable for the duration of the call only when given one, so nested public encoders inherit the caller's choice. Each node encoder reads it once.</p>
+<p>Alternative: a parameter on every internal encoder. Rejected because about 50 recursive call sites and the <code>_keyed</code> helpers would each have to forward it, and one missed forward would silently mix spellings. The context variable is task- and thread-local, matches morphir-core's design, and tests check both spellings over every node kind.</p>
+<h3>CDC-2. Compact only nodes without attributes</h3>
+<p>Each node first builds its expanded members as today, then returns the compact form when its attributes are empty. The table follows morphir-core's <code>serialize_compact_type</code>, <code>serialize_value</code>, <code>serialize_pattern</code> and <code>serialize_literal</code>.</p>
+<table>
+<thead><tr><th>Node</th><th>Compact form</th></tr></thead>
+<tbody>
+<tr><td>Type Variable / argument-free Reference</td><td><code>"a"</code> / <code>"pkg:mod#name"</code></td></tr>
+<tr><td>Type Reference with arguments</td><td><code>{"Reference": [fqname, arg, ...]}</code></td></tr>
+<tr><td>Type Tuple</td><td><code>{"Tuple": [type, ...]}</code></td></tr>
+<tr><td>Record, ExtensibleRecord, Function, Unit, Union types</td><td>Wrapper without <code>attributes</code>, as today</td></tr>
+<tr><td>Literal</td><td><code>{"IntegerLiteral": 42}</code></td></tr>
+<tr><td>Literal, Constructor, Reference, Variable, FieldFunction, Tuple, List values</td><td>Payload directly under the tag</td></tr>
+<tr><td>TuplePattern / LiteralPattern</td><td>Pattern list / literal directly under the tag</td></tr>
+</tbody>
+</table>
+<h3>CDC-3. Flatten documentation in both spellings</h3>
+<p><code>_encode_documented</code> writes <code>{"doc": text, **members}</code> with <code>doc</code> first. Decision 0010 makes this the canonical form, and the nested wrapper is only a reader compatibility spelling, so the expanded spelling uses it as well. A documented node whose encoding is not an object, such as a compact string type, cannot occur at the documented positions: type and value definitions and specifications are always objects. The encoder fails with <code>no_v4_spelling</code> if it ever does.</p>
+<h3>CLI-1. Expose the choice in <code>ir convert</code> only</h3>
+<p><code>ir convert --to v4</code> gains <code>--v4-spelling compact|expanded</code>, default <code>compact</code>. <code>compile --ir-version v4</code> writes the default compact spelling, which is also what the native compiler emits.</p>
+
+<h2 id="risks">Risks and trade-offs</h2>
+<table>
+<thead><tr><th>Risk</th><th>Mitigation</th></tr></thead>
+<tbody>
+<tr><td>A downstream reader accepts only the expanded spelling</td><td><code>--v4-spelling expanded</code> and <code>Spelling.EXPANDED</code>; the proposal marks the change BREAKING.</td></tr>
+<tr><td>Compact and expanded spellings mix in one document</td><td>A test walks the expanded output of every node kind and finds no compact form. The byte-for-byte fixture test covers the compact side.</td></tr>
+<tr><td>Ambiguous strings</td><td>The reader already separates FQName strings (containing <code>:</code> and <code>#</code>) from names, as the schema patterns do. Round-trip tests cover both.</td></tr>
+</tbody>
+</table>
+
+<h2 id="migration">Migration and rollback</h2>
+<p>This is a minor release of <code>morphir</code> and, for the CLI option, of <code>morphir-python</code>. Readers are unaffected. To roll back, select the expanded spelling or revert the change; no stored data needs migration, because both spellings decode to the same model.</p>
+</main>
+</body>
+</html>
diff --git a/openspec/changes/write-compact-ir-v4/proposal.md b/openspec/changes/write-compact-ir-v4/proposal.md
new file mode 100644
index 00000000..268a605a
--- /dev/null
+++ b/openspec/changes/write-compact-ir-v4/proposal.md
@@ -0,0 +1,31 @@
+# Proposal
+
+## Why
+
+The finos/morphir v4 JSON profile at the codec's pin (`efa36060`) says writers SHOULD emit the compact canonical vocabulary unless expanded output is explicitly selected. The Python v4 writer emits only the expanded spelling and the pre-decision nested `{"doc", "value"}` wrapper. Its output is therefore larger than other Morphir tools' output and spelled differently: it is 30–35% larger than morphir-core's output for the same compiled models (benchmark run 20261027T194412Z). The reader half landed with the Python binding migration; this change does the writer half of `morphir-ukvn.8.16`.
+
+## What Changes
+
+- The v4 encoders write the compact canonical spelling by default. A node without attributes uses its shortest schema-valid form: a type variable as its name string; a type reference without arguments as its FQName string, or `{"Reference": [fqname, args...]}` with arguments; a tuple type as `{"Tuple": [...]}`; a literal as `{"Kind": payload}`; `Literal`, `Constructor`, `Reference`, `Variable`, `FieldFunction`, `Tuple` and `List` values, and `TuplePattern` and `LiteralPattern` patterns, with the payload directly under the tag. A node that carries attributes keeps the expanded spelling.
+- Documentation is written flattened, with `doc` first beside the documented node's members (decision 0010), instead of the nested `{"doc", "value"}` wrapper.
+- Callers can still select the expanded spelling: `Spelling.EXPANDED` in the library, `--v4-spelling expanded` in `morphir-python ir convert`. **BREAKING** for consumers that parse v4 JSON written by this library and accept only the expanded spelling; every schema-valid reader, including this library and morphir-core, reads both.
+- Out of scope, still waiting for upstream v4 to settle: legacy-spelling warnings, kit diagnostic renames, `Union` and 4.1.0 linked annotations, and the morphir-diwy downgrade code names.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `ir/v4`: the writer's default spelling, flattened documentation, and spelling selection.
+- `tools/ir-interchange`: `ir convert --to v4` writes the compact spelling by default and offers `--v4-spelling`.
+
+## Beads
+
+- **Tracked by**: `morphir-ukvn.8.16` (writer half; its other scope stays deferred on upstream).
+
+## Impact
+
+`packages/morphir/src/morphir/ir/v4/codec.py`, its tests, the `ir convert` command and documentation. Encoded v4 output changes shape, but the decoded model does not. Generation in `morphir_tools.python` sends compact v4 to the native compiler, which reads both spellings.
diff --git a/openspec/changes/write-compact-ir-v4/specs/ir/v4/spec.md b/openspec/changes/write-compact-ir-v4/specs/ir/v4/spec.md
new file mode 100644
index 00000000..20fe4a3a
--- /dev/null
+++ b/openspec/changes/write-compact-ir-v4/specs/ir/v4/spec.md
@@ -0,0 +1,32 @@
+# Spec Delta
+
+## ADDED Requirements
+
+### Requirement: Write the compact canonical v4 spelling
+By default, the v4 encoders SHALL write the compact canonical spelling of the pinned finos/morphir v4 JSON profile, as morphir-core writes it at the same profile. A node without attributes SHALL use its shortest schema-valid form, and a node that carries attributes SHALL keep the expanded spelling with `attributes` first. (bead: morphir-ukvn.8.16)
+
+#### Scenario: Compiler output re-encodes byte for byte
+- **WHEN** a v4 document written by morphir-core 0.2.0 for a compiled Python model is decoded and encoded with the default spelling
+- **THEN** the encoded JSON equals the original document, including member order
+
+#### Scenario: Compact node forms
+- **WHEN** a model with type variables, argument-free and applied type references, tuples, literals, variables, references, constructors, field functions, lists, tuple patterns and literal patterns is encoded
+- **THEN** they are written as name or FQName strings, `{"Reference": [fqname, args...]}`, `{"Tuple": [...]}`, `{"Kind": payload}` literals, and wrappers holding their payload directly
+
+#### Scenario: Attributes keep the expanded spelling
+- **WHEN** a type or value carrying a source location or an inferred type is encoded
+- **THEN** that node is written in the expanded spelling with `attributes` first, while nodes without attributes stay compact
+
+### Requirement: Write documentation flattened
+The v4 encoders SHALL write documentation flattened, with `doc` first beside the documented node's own members (decision 0010), and SHALL NOT write the nested `{"doc", "value"}` wrapper. (bead: morphir-ukvn.8.16)
+
+#### Scenario: Documented type definition
+- **WHEN** a documented type definition is encoded
+- **THEN** `doc` is its first member, followed by the definition's members, and decoding returns the same documentation and definition
+
+### Requirement: Select the expanded spelling
+Callers SHALL be able to select the expanded spelling, which writes every node in its expanded form. Both spellings SHALL decode to the model that was encoded. (bead: morphir-ukvn.8.16)
+
+#### Scenario: Expanded spelling on request
+- **WHEN** a caller selects the expanded spelling for a model
+- **THEN** every node is written expanded, and decoding returns the same model as decoding the default output
diff --git a/openspec/changes/write-compact-ir-v4/specs/tools/ir-interchange/spec.md b/openspec/changes/write-compact-ir-v4/specs/tools/ir-interchange/spec.md
new file mode 100644
index 00000000..11f2b500
--- /dev/null
+++ b/openspec/changes/write-compact-ir-v4/specs/tools/ir-interchange/spec.md
@@ -0,0 +1,14 @@
+# Spec Delta
+
+## ADDED Requirements
+
+### Requirement: Choose the v4 spelling on conversion
+`ir convert --to v4` SHALL write the compact canonical spelling by default and SHALL accept `--v4-spelling expanded` to write the expanded spelling. The option SHALL be rejected as a usage error with any other value, and SHALL have no effect on v3 output. (bead: morphir-ukvn.8.16)
+
+#### Scenario: Default conversion is compact
+- **WHEN** the user converts a format 3 file with `ir convert --to v4`
+- **THEN** the written document uses compact spellings, such as type references as FQName strings, and `ir inspect` reads it
+
+#### Scenario: Expanded conversion on request
+- **WHEN** the user adds `--v4-spelling expanded`
+- **THEN** the written document uses the expanded spellings and decodes to the same model as the compact output
diff --git a/openspec/changes/write-compact-ir-v4/tasks.md b/openspec/changes/write-compact-ir-v4/tasks.md
new file mode 100644
index 00000000..e36504c5
--- /dev/null
+++ b/openspec/changes/write-compact-ir-v4/tasks.md
@@ -0,0 +1,9 @@
+# Tasks
+
+Implement against `design.html` and the two delta specs. Follow TDD; claim the group bead before work and close it with test and commit evidence.
+
+## 1. Write compact canonical v4 and flattened documentation (morphir-ukvn.8.16.1)
+
+- [x] 1.1 Add `Spelling` and its per-call selection to the v4 encoders, write the compact forms of types, literals, values and patterns without attributes, and keep the expanded form for nodes with attributes; verify that decoding and re-encoding the checked-in morphir-core compiler fixtures gives byte-identical JSON, that a unit test covers each compact node form, and that a test over every node kind finds no compact form in expanded output.
+- [x] 1.2 Write documentation flattened with `doc` first in both spellings; verify round trips of documented type and value definitions and specifications, and refusal with `no_v4_spelling` of a documented node that is not an object.
+- [x] 1.3 Add `--v4-spelling compact|expanded` to `ir convert`, update the codec docstring, README and CLI docs; verify CLI tests for both values and a rejected value, `ir inspect` of compact output, the existing v3/v4 conversion and BDD tests, and `mise run check`.

From 726ac9d800607ef1b79e16e46047f058e4e8da5b Mon Sep 17 00:00:00 2001
From: Damian Reeves <957246+DamianReeves@users.noreply.github.com>
Date: Tue, 27 Oct 2026 20:12:01 -0500
Subject: [PATCH 2/3] feat(ir): write the compact canonical v4 spelling by
 default

The v4 encoders now write a node without attributes in its shortest
schema-valid form, as morphir-core 0.2.0 writes it, and keep the
expanded form for nodes with attributes. Compiler output decodes and
re-encodes byte for byte. Documentation is flattened with doc first
instead of the nested {doc, value} wrapper. Spelling.EXPANDED, passed
as spelling= or selected with use_spelling, writes every node expanded,
and ir convert gains --v4-spelling. Golden files prove the expanded
output is otherwise unchanged; tests that quote expanded upstream or
reader cases now select it explicitly.
---
 packages/morphir-tools/README.md              |   4 +
 .../morphir-tools/src/morphir_tools/cli.py    |  19 +-
 packages/morphir/README.md                    |   7 +
 packages/morphir/src/morphir/ir/v4/codec.py   | 251 +++++++-
 .../ir/python-compiler/adt-v4.expanded.json   | 589 ++++++++++++++++++
 .../python-compiler/modules-v4.expanded.json  | 366 +++++++++++
 tests/tools/test_cli.py                       |  50 ++
 tests/tools/test_python_crosscodec.py         |   3 +-
 tests/unit/ir/test_v4_compact.py              |   9 +-
 tests/unit/ir/test_v4_compact_writer.py       | 285 +++++++++
 tests/unit/ir/test_v4_upstream.py             |  12 +
 11 files changed, 1563 insertions(+), 32 deletions(-)
 create mode 100644 tests/fixtures/ir/python-compiler/adt-v4.expanded.json
 create mode 100644 tests/fixtures/ir/python-compiler/modules-v4.expanded.json
 create mode 100644 tests/unit/ir/test_v4_compact_writer.py

diff --git a/packages/morphir-tools/README.md b/packages/morphir-tools/README.md
index 2abe34e8..de82c229 100644
--- a/packages/morphir-tools/README.md
+++ b/packages/morphir-tools/README.md
@@ -39,6 +39,7 @@ morphir-python ir inspect morphir-ir.json
 morphir-python ir convert morphir-ir.json --to v4 -o out.json --package-version 1.2.0
 morphir-python ir convert v4.json --to v3 -o out.json --drop-source-locations
 morphir-python ir convert old-format-1.json --to v3 -o out.json
+morphir-python ir convert morphir-ir.json --to v4 --v4-spelling expanded -o out.json
 ```
 
 `inspect` prints the normalized format version, the distribution kind
@@ -47,6 +48,9 @@ draft and formats 1 and 2 as legacy. `convert` handles `Library` and `Specs` in
 both directions. It writes a v3 `Library` as format `3` and a v3 `Specs` as
 `"3.1.0"`, the lowest version that holds each. A legacy format 1 or 2 file
 converts to a format 3.0.0 `Library` or draft v4; nothing writes format 1 or 2.
+Draft v4 is written in the compact canonical spelling, as other Morphir tools
+write it; `--v4-spelling expanded` writes every node in the expanded form
+instead. Both spellings read back to the same model.
 `convert` writes through a temporary file and renames it only on success, so a
 failed conversion leaves no output file.
 Diagnostics go to standard error as `code at location: message`.
diff --git a/packages/morphir-tools/src/morphir_tools/cli.py b/packages/morphir-tools/src/morphir_tools/cli.py
index c75c4ae4..721e301a 100644
--- a/packages/morphir-tools/src/morphir_tools/cli.py
+++ b/packages/morphir-tools/src/morphir_tools/cli.py
@@ -53,6 +53,13 @@
 app.add_typer(ir_app, name="ir")
 
 
+class V4Spelling(str, Enum):
+    """The draft v4 JSON spelling to write."""
+
+    COMPACT = "compact"
+    EXPANDED = "expanded"
+
+
 class Target(str, Enum):
     """The IR version to convert to."""
 
@@ -184,6 +191,14 @@ def convert(
             "writing v4, which spells an input as a bare type."
         ),
     ] = False,
+    v4_spelling: Annotated[
+        V4Spelling,
+        typer.Option(
+            "--v4-spelling",
+            help="The v4 JSON spelling to write: compact, the canonical form, or "
+            "expanded. Ignored when writing v3.",
+        ),
+    ] = V4Spelling.COMPACT,
 ) -> None:
     """Convert between format 3 (3.0.x and 3.1.x) and draft IR v4.
 
@@ -209,7 +224,9 @@ def convert(
                 upgraded = Ok(migrated.value, migrated.warnings)
             if drop_input_attributes:
                 upgraded = drop_inputs(upgraded.value)
-            document = v4_codec.encode_versioned_distribution(upgraded.value)
+            document = v4_codec.encode_versioned_distribution(
+                upgraded.value, spelling=v4_codec.Spelling(v4_spelling.value)
+            )
             warnings: tuple[Diagnostic, ...] = upgraded.warnings
         else:
             if not _is_v4(version):
diff --git a/packages/morphir/README.md b/packages/morphir/README.md
index faaa6c4e..ea65c282 100644
--- a/packages/morphir/README.md
+++ b/packages/morphir/README.md
@@ -177,6 +177,13 @@ the distribution wrapped by its kind, never a format-3 shape. The module
 docstring lists the gaps between the Python v4 model and upstream v4, each of
 which fails with a diagnostic instead of guessing or dropping data.
 
+The reader accepts every spelling the pinned schema allows. The writer emits the
+compact canonical spelling that the profile prefers and Rust `morphir-core`
+writes, so `{"Reference": {"fqname": "morphir/SDK:basics#int"}}` is written as
+`"morphir/SDK:basics#int"`. Pass `spelling=v4_codec.Spelling.EXPANDED`, or use
+`with v4_codec.use_spelling(v4_codec.Spelling.EXPANDED):`, to write every node in
+the expanded form. Both spellings decode to the same model.
+
 The v4 model follows the upstream reference model at that commit:
 
 - A value definition is one of four bodies (`ValueDefinitionBody`): the
diff --git a/packages/morphir/src/morphir/ir/v4/codec.py b/packages/morphir/src/morphir/ir/v4/codec.py
index 25b0f9de..b308175c 100644
--- a/packages/morphir/src/morphir/ir/v4/codec.py
+++ b/packages/morphir/src/morphir/ir/v4/codec.py
@@ -9,8 +9,16 @@
 the distribution wrapped by its kind (``Library``, ``Specs``, or ``Application``).
 The codec never writes a format-3 tagged-array shape.
 
-The writer emits every node in the schema's expanded form, ``{"Kind": {members}}``,
-with ``attributes`` omitted when empty. The profile says that readers MUST accept
+The writer emits the compact canonical spelling by default, as the profile asks
+and as Rust ``morphir-core`` writes it: a node without attributes takes its
+shortest form (a type variable or argument-free reference as a string, a literal
+as ``{"Kind": payload}``, a variable as ``{"Variable": "x"}``, a tuple as
+``{"Tuple": [...]}``), and a node with attributes keeps the expanded form
+``{"Kind": {"attributes": ..., members}}``. `Spelling.EXPANDED`, passed as
+``spelling=`` or selected with `use_spelling`, writes every node expanded.
+Documentation is written flattened, ``doc`` first beside the documented type or
+value (decision 0010); a module definition writes its ``doc`` after ``types``
+and ``values``. The profile says that readers MUST accept
 every spelling the v4 JSON Schema marks as valid, so the reader also accepts the
 compact canonical vocabulary that Rust ``morphir-core`` writes, and the legacy
 spellings that the schema itself lists. Each spelling of a node gives the same
@@ -93,8 +101,6 @@
   (upstream makes them definition bodies); encoding fails with ``no_v4_spelling``.
 - Structured ``TypeConstraints`` (deprecated) have no spelling; encoding fails
   with ``no_v4_spelling``.
-- The writer emits only the expanded spelling, not the compact canonical one the
-  profile prefers.
 - The reader refuses the decision-0006 legacy-window spellings that the pinned
   schema marks invalid (``attrs``, ``thenBranch``, ``argumentType``, a record's
   field map directly under ``Record``, the nested ``{"value": ...}`` wrapper with
@@ -129,8 +135,11 @@
 
 import math
 import re
-from collections.abc import Callable, Collection
+from collections.abc import Callable, Collection, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
 from decimal import Decimal, InvalidOperation
+from enum import Enum
 from typing import Any
 
 from .. import diagnostics as d
@@ -809,14 +818,91 @@ def _with_attributes(
     return {"attributes": attrs, **members} if attrs else members
 
 
+class Spelling(Enum):
+    """Which v4 JSON spelling the encoders write.
+
+    ``COMPACT``, the default, is the canonical spelling the v4 JSON profile asks
+    writers to emit, as morphir-core writes it: a node without attributes takes
+    its shortest schema-valid form. ``EXPANDED`` writes every node as
+    ``{"Kind": {members}}``. Both decode to the same model, and both write
+    documentation flattened beside the node it documents (decision 0010).
+    """
+
+    COMPACT = "compact"
+    EXPANDED = "expanded"
+
+
+_SPELLING: ContextVar[Spelling] = ContextVar(
+    "morphir_ir_v4_spelling", default=Spelling.COMPACT
+)
+
+
+@contextmanager
+def use_spelling(spelling: Spelling | None) -> Iterator[None]:
+    """Use ``spelling`` for the v4 encoders called inside the block.
+
+    The selection is local to the current thread or task. ``None`` keeps the
+    selection already in effect.
+
+    Example:
+        >>> from morphir.ir.v4 import codec
+        >>> with codec.use_spelling(codec.Spelling.EXPANDED):
+        ...     codec.encode_type(codec.decode_type("a"))
+        {'Variable': {'name': 'a'}}
+    """
+    if spelling is None:
+        yield
+        return
+    token = _SPELLING.set(spelling)
+    try:
+        yield
+    finally:
+        _SPELLING.reset(token)
+
+
+def _compact(attrs: dict[str, Json]) -> bool:
+    return not attrs and _SPELLING.get() is Spelling.COMPACT
+
+
+# The member a compact value or pattern writes directly under its tag.
+_PAYLOAD = {
+    "Literal": "literal",
+    "Constructor": "fqname",
+    "Reference": "fqname",
+    "Variable": "name",
+    "FieldFunction": "name",
+    "Tuple": "elements",
+    "List": "items",
+    "TuplePattern": "patterns",
+    "LiteralPattern": "literal",
+}
+
+
 # --- Types ---
 
 
-def encode_type(tpe: t.Type, loc: Location = ()) -> Json:
-    """Encode a v4 type in the expanded draft spelling."""
+def encode_type(
+    tpe: t.Type, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode a v4 type, compact unless ``spelling`` or the caller selects expanded."""
+    with use_spelling(spelling):
+        return _encode_type(tpe, loc)
+
+
+def _encode_type(tpe: t.Type, loc: Location) -> Json:
     attrs = _encode_type_attributes(tpe.attributes, loc)
 
     def node(tag: str, members: dict[str, Json]) -> Json:
+        if _compact(attrs):
+            match tag:
+                case "Variable":
+                    return members["name"]
+                case "Reference" if "args" in members:
+                    return {"Reference": [members["fqname"], *members["args"]]}
+                case "Reference":
+                    return members["fqname"]
+                case "Tuple":
+                    return {"Tuple": members["elements"]}
         return _wrap(tag, _with_attributes(attrs, members))
 
     here = (*loc, type(tpe).__name__)
@@ -1231,12 +1317,21 @@ def _decode_literal_spelling(
 # --- Patterns ---
 
 
-def encode_pattern(p: v.Pattern, loc: Location = ()) -> Json:
-    """Encode a v4 pattern in the expanded draft spelling."""
+def encode_pattern(
+    p: v.Pattern, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode a v4 pattern, compact unless ``spelling`` or the caller selects expanded."""
+    with use_spelling(spelling):
+        return _encode_pattern(p, loc)
+
+
+def _encode_pattern(p: v.Pattern, loc: Location) -> Json:
     attrs = _encode_value_attributes(p.attributes, loc)
     here = (*loc, type(p).__name__)
 
     def node(tag: str, members: dict[str, Json]) -> Json:
+        if _compact(attrs) and tag in _PAYLOAD:
+            return {tag: members[_PAYLOAD[tag]]}
         return _wrap(tag, _with_attributes(attrs, members))
 
     def many(items: list[v.Pattern], key: str) -> list[Json]:
@@ -1336,13 +1431,20 @@ def many(key: str) -> list[v.Pattern]:
 # --- Values ---
 
 
-def encode_value(val: v.Value, loc: Location = ()) -> Json:
-    """Encode a v4 value in the expanded draft spelling.
+def encode_value(
+    val: v.Value, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode a v4 value, compact unless ``spelling`` or the caller selects expanded.
 
     Raises:
         DiagnosticError: With ``no_v4_spelling`` for ``Native`` and ``External``
             nodes, or ``duplicate_member`` for repeated record fields.
     """
+    with use_spelling(spelling):
+        return _encode_value(val, loc)
+
+
+def _encode_value(val: v.Value, loc: Location) -> Json:
     construct = type(val).__name__
     here = (*loc, construct)
     if isinstance(val, (v.Native, v.External)):
@@ -1356,6 +1458,8 @@ def encode_value(val: v.Value, loc: Location = ()) -> Json:
     attrs = _encode_value_attributes(val.attributes, loc)
 
     def node(tag: str, members: dict[str, Json]) -> Json:
+        if _compact(attrs) and tag in _PAYLOAD:
+            return {tag: members[_PAYLOAD[tag]]}
         return _wrap(tag, _with_attributes(attrs, members))
 
     def sub(x: v.Value, key: str) -> Json:
@@ -1833,7 +1937,17 @@ def _decode_externals(j: object, loc: Location) -> list[v.ExternalBinding]:
     return bindings
 
 
-def encode_value_definition(defn: v.ValueDefinitionBody, loc: Location = ()) -> Json:
+def encode_value_definition(
+    defn: v.ValueDefinitionBody, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode with `Spelling.COMPACT` unless `spelling` or the caller selects otherwise."""
+    with use_spelling(spelling):
+        return _encode_value_definition_body(defn, loc)
+
+
+def _encode_value_definition_body(
+    defn: v.ValueDefinitionBody, loc: Location = ()
+) -> Json:
     """Encode a value definition as ``{"<Kind>Body": {...}}``.
 
     Raises:
@@ -1950,7 +2064,15 @@ def optional_value(key: str) -> v.Value | None:
             )
 
 
-def encode_value_specification(spec: v.Specification, loc: Location = ()) -> Json:
+def encode_value_specification(
+    spec: v.Specification, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode with `Spelling.COMPACT` unless `spelling` or the caller selects otherwise."""
+    with use_spelling(spelling):
+        return _encode_value_specification_body(spec, loc)
+
+
+def _encode_value_specification_body(spec: v.Specification, loc: Location = ()) -> Json:
     return _with_annotations(
         spec.annotations,
         loc,
@@ -2151,7 +2273,15 @@ def _decode_ctor_args(j: object, loc: Location) -> list[tuple[Name, t.Type]]:
     return _decode_list(_decode_name_type_pair, j, loc, "Constructor")
 
 
-def encode_type_specification(spec: ts.Specification, loc: Location = ()) -> Json:
+def encode_type_specification(
+    spec: ts.Specification, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode with `Spelling.COMPACT` unless `spelling` or the caller selects otherwise."""
+    with use_spelling(spelling):
+        return _encode_type_specification_body(spec, loc)
+
+
+def _encode_type_specification_body(spec: ts.Specification, loc: Location = ()) -> Json:
     tag = type(spec).__name__
     encoded = _encode_type_specification(spec, loc)
     return _wrap(tag, _with_annotations(spec.annotations, (*loc, tag), encoded[tag]))
@@ -2256,7 +2386,15 @@ def _decode_legacy_type_specification(
             )
 
 
-def encode_type_definition(defn: td.Definition, loc: Location = ()) -> Json:
+def encode_type_definition(
+    defn: td.Definition, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode with `Spelling.COMPACT` unless `spelling` or the caller selects otherwise."""
+    with use_spelling(spelling):
+        return _encode_type_definition_body(defn, loc)
+
+
+def _encode_type_definition_body(defn: td.Definition, loc: Location = ()) -> Json:
     params = _encode_params(defn.type_params, loc)
     match defn:
         case td.TypeAliasDefinition(_, tpe):
@@ -2335,9 +2473,19 @@ def _encode_documented[A](
     encode: Callable[[A, Location], Json],
 ) -> Callable[[Documented[A], Location], Json]:
     def run(item: Documented[A], loc: Location) -> Json:
+        encoded = encode(item.value, loc)
         if item.doc is None:
-            return encode(item.value, loc)
-        return {"doc": item.doc, "value": encode(item.value, (*loc, "value"))}
+            return encoded
+        if not isinstance(encoded, dict):
+            raise fail(
+                d.NO_V4_SPELLING,
+                "doc",
+                loc,
+                "documentation is flattened beside the node it documents, "
+                "so the node must be a JSON object",
+            )
+        # Decision 0010: `doc` is a flattened member placed first.
+        return {"doc": item.doc, **encoded}
 
     return run
 
@@ -2471,7 +2619,17 @@ def _decode_doc(obj: dict[str, object], loc: Location) -> str | None:
     return _expect_str(obj["doc"], (*loc, "doc"), "doc")
 
 
-def encode_module_specification(spec: module.Specification, loc: Location = ()) -> Json:
+def encode_module_specification(
+    spec: module.Specification, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode with `Spelling.COMPACT` unless `spelling` or the caller selects otherwise."""
+    with use_spelling(spelling):
+        return _encode_module_specification_body(spec, loc)
+
+
+def _encode_module_specification_body(
+    spec: module.Specification, loc: Location = ()
+) -> Json:
     return _with_annotations(
         spec.annotations,
         loc,
@@ -2518,7 +2676,15 @@ def decode_module_specification(j: object, loc: Location = ()) -> module.Specifi
     )
 
 
-def encode_module_definition(defn: module.Definition, loc: Location = ()) -> Json:
+def encode_module_definition(
+    defn: module.Definition, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode with `Spelling.COMPACT` unless `spelling` or the caller selects otherwise."""
+    with use_spelling(spelling):
+        return _encode_module_definition_body(defn, loc)
+
+
+def _encode_module_definition_body(defn: module.Definition, loc: Location = ()) -> Json:
     return _with_doc(
         {
             "types": _keyed(
@@ -2563,6 +2729,14 @@ def decode_module_definition(j: object, loc: Location = ()) -> module.Definition
 
 
 def encode_package_specification(
+    spec: package.Specification, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode with `Spelling.COMPACT` unless `spelling` or the caller selects otherwise."""
+    with use_spelling(spelling):
+        return _encode_package_specification_body(spec, loc)
+
+
+def _encode_package_specification_body(
     spec: package.Specification, loc: Location = ()
 ) -> Json:
     return {
@@ -2594,7 +2768,17 @@ def decode_package_specification(
     )
 
 
-def encode_package_definition(defn: package.Definition, loc: Location = ()) -> Json:
+def encode_package_definition(
+    defn: package.Definition, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode with `Spelling.COMPACT` unless `spelling` or the caller selects otherwise."""
+    with use_spelling(spelling):
+        return _encode_package_definition_body(defn, loc)
+
+
+def _encode_package_definition_body(
+    defn: package.Definition, loc: Location = ()
+) -> Json:
     return {
         "modules": _keyed(
             defn.modules, _path_key, _enc_module_def, (*loc, "modules"), "modules"
@@ -2651,7 +2835,15 @@ def _decode_entry_point(j: object, loc: Location) -> EntryPoint:
     )
 
 
-def encode_distribution(dist: Distribution, loc: Location = ()) -> Json:
+def encode_distribution(
+    dist: Distribution, loc: Location = (), *, spelling: Spelling | None = None
+) -> Json:
+    """Encode with `Spelling.COMPACT` unless `spelling` or the caller selects otherwise."""
+    with use_spelling(spelling):
+        return _encode_distribution_body(dist, loc)
+
+
+def _encode_distribution_body(dist: Distribution, loc: Location = ()) -> Json:
     """Encode a distribution wrapped by its kind.
 
     The package release version is not written; the v4 profile has no member for it.
@@ -2772,17 +2964,24 @@ def decode_distribution(j: object, loc: Location = ()) -> Distribution:
             )
 
 
-def encode_versioned_distribution(dist: Distribution) -> dict[str, Json]:
+def encode_versioned_distribution(
+    dist: Distribution, *, spelling: Spelling | None = None
+) -> dict[str, Json]:
     """Encode ``{"formatVersion": 4, "distribution": ...}``, version first.
 
+    Args:
+        dist: The distribution to encode.
+        spelling: `Spelling.COMPACT`, the default, or `Spelling.EXPANDED`.
+
     Raises:
         DiagnosticError: When the distribution uses a construct with no draft
             spelling.
     """
-    return {
-        "formatVersion": write_format_version(V4),
-        "distribution": encode_distribution(dist, ("distribution",)),
-    }
+    with use_spelling(spelling):
+        return {
+            "formatVersion": write_format_version(V4),
+            "distribution": encode_distribution(dist, ("distribution",)),
+        }
 
 
 def decode_versioned_distribution(document: str | object) -> Distribution:
diff --git a/tests/fixtures/ir/python-compiler/adt-v4.expanded.json b/tests/fixtures/ir/python-compiler/adt-v4.expanded.json
new file mode 100644
index 00000000..cb54f48e
--- /dev/null
+++ b/tests/fixtures/ir/python-compiler/adt-v4.expanded.json
@@ -0,0 +1,589 @@
+{
+ "formatVersion": 4,
+ "distribution": {
+  "Library": {
+   "packageName": "acme/example",
+   "dependencies": {},
+   "def": {
+    "modules": {
+     "models": {
+      "Public": {
+       "types": {
+        "address": {
+         "Public": {
+          "TypeAliasDefinition": {
+           "typeParams": [],
+           "typeExp": {
+            "Record": {
+             "fields": {
+              "street": {
+               "Reference": {
+                "fqname": "morphir/SDK:string#string"
+               }
+              },
+              "zip-code": {
+               "Reference": {
+                "fqname": "morphir/SDK:basics#int"
+               }
+              }
+             }
+            }
+           }
+          }
+         }
+        },
+        "application": {
+         "Public": {
+          "TypeAliasDefinition": {
+           "typeParams": [],
+           "typeExp": {
+            "Record": {
+             "fields": {
+              "decision": {
+               "Reference": {
+                "fqname": "acme/example:models#decision"
+               }
+              },
+              "verified": {
+               "Reference": {
+                "fqname": "morphir/SDK:basics#bool"
+               }
+              },
+              "coordinates": {
+               "Tuple": {
+                "elements": [
+                 {
+                  "Reference": {
+                   "fqname": "morphir/SDK:basics#float"
+                  }
+                 },
+                 {
+                  "Reference": {
+                   "fqname": "morphir/SDK:basics#float"
+                  }
+                 }
+                ]
+               }
+              }
+             }
+            }
+           }
+          }
+         }
+        },
+        "decision": {
+         "Public": {
+          "CustomTypeDefinition": {
+           "typeParams": [],
+           "access": "Public",
+           "constructors": {
+            "pending": [],
+            "approved": [
+             [
+              "amount",
+              {
+               "Reference": {
+                "fqname": "morphir/SDK:basics#float"
+               }
+              }
+             ],
+             [
+              "address",
+              {
+               "Reference": {
+                "fqname": "acme/example:models#address"
+               }
+              }
+             ]
+            ]
+           }
+          }
+         }
+        },
+        "labeled-point": {
+         "Public": {
+          "TypeAliasDefinition": {
+           "typeParams": [],
+           "typeExp": {
+            "Tuple": {
+             "elements": [
+              {
+               "Reference": {
+                "fqname": "acme/example:models#point"
+               }
+              },
+              {
+               "Reference": {
+                "fqname": "morphir/SDK:string#string"
+               }
+              }
+             ]
+            }
+           }
+          }
+         }
+        },
+        "point": {
+         "Public": {
+          "TypeAliasDefinition": {
+           "typeParams": [],
+           "typeExp": {
+            "Tuple": {
+             "elements": [
+              {
+               "Reference": {
+                "fqname": "morphir/SDK:basics#float"
+               }
+              },
+              {
+               "Reference": {
+                "fqname": "morphir/SDK:basics#float"
+               }
+              }
+             ]
+            }
+           }
+          }
+         }
+        }
+       },
+       "values": {
+        "choose": {
+         "Public": {
+          "ExpressionBody": {
+           "inputTypes": {
+            "flag": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#bool"
+             }
+            },
+            "first": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#int"
+             }
+            },
+            "second": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#int"
+             }
+            }
+           },
+           "outputType": {
+            "Reference": {
+             "fqname": "morphir/SDK:basics#int"
+            }
+           },
+           "body": {
+            "IfThenElse": {
+             "condition": {
+              "Variable": {
+               "name": "flag"
+              }
+             },
+             "then": {
+              "Variable": {
+               "name": "first"
+              }
+             },
+             "else": {
+              "Variable": {
+               "name": "second"
+              }
+             }
+            }
+           }
+          }
+         }
+        },
+        "classify": {
+         "Public": {
+          "ExpressionBody": {
+           "inputTypes": {
+            "value": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#int"
+             }
+            }
+           },
+           "outputType": {
+            "Reference": {
+             "fqname": "morphir/SDK:string#string"
+            }
+           },
+           "body": {
+            "IfThenElse": {
+             "condition": {
+              "Apply": {
+               "function": {
+                "Apply": {
+                 "function": {
+                  "Reference": {
+                   "fqname": "morphir/SDK:basics#less-than"
+                  }
+                 },
+                 "argument": {
+                  "Variable": {
+                   "name": "value"
+                  }
+                 }
+                }
+               },
+               "argument": {
+                "Literal": {
+                 "literal": {
+                  "IntegerLiteral": 0
+                 }
+                }
+               }
+              }
+             },
+             "then": {
+              "Literal": {
+               "literal": {
+                "StringLiteral": "negative"
+               }
+              }
+             },
+             "else": {
+              "IfThenElse": {
+               "condition": {
+                "Apply": {
+                 "function": {
+                  "Apply": {
+                   "function": {
+                    "Reference": {
+                     "fqname": "morphir/SDK:basics#equal"
+                    }
+                   },
+                   "argument": {
+                    "Variable": {
+                     "name": "value"
+                    }
+                   }
+                  }
+                 },
+                 "argument": {
+                  "Literal": {
+                   "literal": {
+                    "IntegerLiteral": 0
+                   }
+                  }
+                 }
+                }
+               },
+               "then": {
+                "Literal": {
+                 "literal": {
+                  "StringLiteral": "zero"
+                 }
+                }
+               },
+               "else": {
+                "Literal": {
+                 "literal": {
+                  "StringLiteral": "positive"
+                 }
+                }
+               }
+              }
+             }
+            }
+           }
+          }
+         }
+        },
+        "expression": {
+         "Public": {
+          "ExpressionBody": {
+           "inputTypes": {
+            "flag": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#bool"
+             }
+            }
+           },
+           "outputType": {
+            "Reference": {
+             "fqname": "morphir/SDK:basics#float"
+            }
+           },
+           "body": {
+            "IfThenElse": {
+             "condition": {
+              "Variable": {
+               "name": "flag"
+              }
+             },
+             "then": {
+              "Literal": {
+               "literal": {
+                "FloatLiteral": -1.5
+               }
+              }
+             },
+             "else": {
+              "Literal": {
+               "literal": {
+                "FloatLiteral": 2.5
+               }
+              }
+             }
+            }
+           }
+          }
+         }
+        },
+        "guarded": {
+         "Public": {
+          "ExpressionBody": {
+           "inputTypes": {
+            "first": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#bool"
+             }
+            },
+            "second": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#bool"
+             }
+            }
+           },
+           "outputType": {
+            "Reference": {
+             "fqname": "morphir/SDK:basics#int"
+            }
+           },
+           "body": {
+            "IfThenElse": {
+             "condition": {
+              "Variable": {
+               "name": "first"
+              }
+             },
+             "then": {
+              "IfThenElse": {
+               "condition": {
+                "Variable": {
+                 "name": "second"
+                }
+               },
+               "then": {
+                "Literal": {
+                 "literal": {
+                  "IntegerLiteral": 1
+                 }
+                }
+               },
+               "else": {
+                "Literal": {
+                 "literal": {
+                  "IntegerLiteral": 2
+                 }
+                }
+               }
+              }
+             },
+             "else": {
+              "Literal": {
+               "literal": {
+                "IntegerLiteral": 2
+               }
+              }
+             }
+            }
+           }
+          }
+         }
+        },
+        "located": {
+         "Public": {
+          "ExpressionBody": {
+           "inputTypes": {
+            "flag": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#bool"
+             }
+            },
+            "location": {
+             "Reference": {
+              "fqname": "acme/example:models#point"
+             }
+            }
+           },
+           "outputType": {
+            "Reference": {
+             "fqname": "acme/example:models#labeled-point"
+            }
+           },
+           "body": {
+            "IfThenElse": {
+             "condition": {
+              "Variable": {
+               "name": "flag"
+              }
+             },
+             "then": {
+              "Tuple": {
+               "elements": [
+                {
+                 "Variable": {
+                  "name": "location"
+                 }
+                },
+                {
+                 "Literal": {
+                  "literal": {
+                   "StringLiteral": "known"
+                  }
+                 }
+                }
+               ]
+              }
+             },
+             "else": {
+              "Tuple": {
+               "elements": [
+                {
+                 "Tuple": {
+                  "elements": [
+                   {
+                    "Literal": {
+                     "literal": {
+                      "FloatLiteral": 0.0
+                     }
+                    }
+                   },
+                   {
+                    "Literal": {
+                     "literal": {
+                      "FloatLiteral": 0.0
+                     }
+                    }
+                   }
+                  ]
+                 }
+                },
+                {
+                 "Literal": {
+                  "literal": {
+                   "StringLiteral": "unknown"
+                  }
+                 }
+                }
+               ]
+              }
+             }
+            }
+           }
+          }
+         }
+        },
+        "make-point": {
+         "Public": {
+          "ExpressionBody": {
+           "inputTypes": {
+            "x": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#float"
+             }
+            },
+            "y": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#float"
+             }
+            }
+           },
+           "outputType": {
+            "Reference": {
+             "fqname": "acme/example:models#point"
+            }
+           },
+           "body": {
+            "Tuple": {
+             "elements": [
+              {
+               "Variable": {
+                "name": "x"
+               }
+              },
+              {
+               "Variable": {
+                "name": "y"
+               }
+              }
+             ]
+            }
+           }
+          }
+         }
+        },
+        "nested": {
+         "Public": {
+          "ExpressionBody": {
+           "inputTypes": {
+            "first": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#bool"
+             }
+            },
+            "second": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#bool"
+             }
+            }
+           },
+           "outputType": {
+            "Reference": {
+             "fqname": "morphir/SDK:basics#int"
+            }
+           },
+           "body": {
+            "IfThenElse": {
+             "condition": {
+              "Variable": {
+               "name": "first"
+              }
+             },
+             "then": {
+              "IfThenElse": {
+               "condition": {
+                "Variable": {
+                 "name": "second"
+                }
+               },
+               "then": {
+                "Literal": {
+                 "literal": {
+                  "IntegerLiteral": 1
+                 }
+                }
+               },
+               "else": {
+                "Literal": {
+                 "literal": {
+                  "IntegerLiteral": 2
+                 }
+                }
+               }
+              }
+             },
+             "else": {
+              "Literal": {
+               "literal": {
+                "IntegerLiteral": 3
+               }
+              }
+             }
+            }
+           }
+          }
+         }
+        }
+       }
+      }
+     }
+    }
+   }
+  }
+ }
+}
diff --git a/tests/fixtures/ir/python-compiler/modules-v4.expanded.json b/tests/fixtures/ir/python-compiler/modules-v4.expanded.json
new file mode 100644
index 00000000..93d8048f
--- /dev/null
+++ b/tests/fixtures/ir/python-compiler/modules-v4.expanded.json
@@ -0,0 +1,366 @@
+{
+ "formatVersion": 4,
+ "distribution": {
+  "Library": {
+   "packageName": "acme/example",
+   "dependencies": {},
+   "def": {
+    "modules": {
+     "models": {
+      "Public": {
+       "types": {
+        "address": {
+         "Public": {
+          "TypeAliasDefinition": {
+           "typeParams": [],
+           "typeExp": {
+            "Record": {
+             "fields": {
+              "street": {
+               "Reference": {
+                "fqname": "morphir/SDK:string#string"
+               }
+              },
+              "zip-code": {
+               "Reference": {
+                "fqname": "morphir/SDK:basics#int"
+               }
+              }
+             }
+            }
+           }
+          }
+         }
+        },
+        "application": {
+         "Public": {
+          "TypeAliasDefinition": {
+           "typeParams": [],
+           "typeExp": {
+            "Record": {
+             "fields": {
+              "decision": {
+               "Reference": {
+                "fqname": "acme/example:models#decision"
+               }
+              },
+              "verified": {
+               "Reference": {
+                "fqname": "morphir/SDK:basics#bool"
+               }
+              },
+              "coordinates": {
+               "Tuple": {
+                "elements": [
+                 {
+                  "Reference": {
+                   "fqname": "morphir/SDK:basics#float"
+                  }
+                 },
+                 {
+                  "Reference": {
+                   "fqname": "morphir/SDK:basics#float"
+                  }
+                 }
+                ]
+               }
+              }
+             }
+            }
+           }
+          }
+         }
+        },
+        "decision": {
+         "Public": {
+          "CustomTypeDefinition": {
+           "typeParams": [],
+           "access": "Public",
+           "constructors": {
+            "pending": [],
+            "approved": [
+             [
+              "amount",
+              {
+               "Reference": {
+                "fqname": "morphir/SDK:basics#float"
+               }
+              }
+             ],
+             [
+              "address",
+              {
+               "Reference": {
+                "fqname": "acme/example:models#address"
+               }
+              }
+             ]
+            ]
+           }
+          }
+         }
+        },
+        "labeled-point": {
+         "Public": {
+          "TypeAliasDefinition": {
+           "typeParams": [],
+           "typeExp": {
+            "Tuple": {
+             "elements": [
+              {
+               "Reference": {
+                "fqname": "acme/example:models#point"
+               }
+              },
+              {
+               "Reference": {
+                "fqname": "morphir/SDK:string#string"
+               }
+              }
+             ]
+            }
+           }
+          }
+         }
+        },
+        "point": {
+         "Public": {
+          "TypeAliasDefinition": {
+           "typeParams": [],
+           "typeExp": {
+            "Tuple": {
+             "elements": [
+              {
+               "Reference": {
+                "fqname": "morphir/SDK:basics#float"
+               }
+              },
+              {
+               "Reference": {
+                "fqname": "morphir/SDK:basics#float"
+               }
+              }
+             ]
+            }
+           }
+          }
+         }
+        }
+       },
+       "values": {
+        "located": {
+         "Public": {
+          "ExpressionBody": {
+           "inputTypes": {
+            "flag": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#bool"
+             }
+            },
+            "location": {
+             "Reference": {
+              "fqname": "acme/example:models#point"
+             }
+            }
+           },
+           "outputType": {
+            "Reference": {
+             "fqname": "acme/example:models#labeled-point"
+            }
+           },
+           "body": {
+            "IfThenElse": {
+             "condition": {
+              "Variable": {
+               "name": "flag"
+              }
+             },
+             "then": {
+              "Tuple": {
+               "elements": [
+                {
+                 "Variable": {
+                  "name": "location"
+                 }
+                },
+                {
+                 "Literal": {
+                  "literal": {
+                   "StringLiteral": "known"
+                  }
+                 }
+                }
+               ]
+              }
+             },
+             "else": {
+              "Tuple": {
+               "elements": [
+                {
+                 "Tuple": {
+                  "elements": [
+                   {
+                    "Literal": {
+                     "literal": {
+                      "FloatLiteral": 0.0
+                     }
+                    }
+                   },
+                   {
+                    "Literal": {
+                     "literal": {
+                      "FloatLiteral": 0.0
+                     }
+                    }
+                   }
+                  ]
+                 }
+                },
+                {
+                 "Literal": {
+                  "literal": {
+                   "StringLiteral": "unknown"
+                  }
+                 }
+                }
+               ]
+              }
+             }
+            }
+           }
+          }
+         }
+        },
+        "make-point": {
+         "Public": {
+          "ExpressionBody": {
+           "inputTypes": {
+            "x": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#float"
+             }
+            },
+            "y": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#float"
+             }
+            }
+           },
+           "outputType": {
+            "Reference": {
+             "fqname": "acme/example:models#point"
+            }
+           },
+           "body": {
+            "Tuple": {
+             "elements": [
+              {
+               "Variable": {
+                "name": "x"
+               }
+              },
+              {
+               "Variable": {
+                "name": "y"
+               }
+              }
+             ]
+            }
+           }
+          }
+         }
+        }
+       }
+      }
+     },
+     "rules": {
+      "Public": {
+       "types": {},
+       "values": {
+        "origin": {
+         "Public": {
+          "ExpressionBody": {
+           "inputTypes": {},
+           "outputType": {
+            "Reference": {
+             "fqname": "acme/example:models#point"
+            }
+           },
+           "body": {
+            "Tuple": {
+             "elements": [
+              {
+               "Literal": {
+                "literal": {
+                 "FloatLiteral": 0.0
+                }
+               }
+              },
+              {
+               "Literal": {
+                "literal": {
+                 "FloatLiteral": 0.0
+                }
+               }
+              }
+             ]
+            }
+           }
+          }
+         }
+        },
+        "select-decision": {
+         "Public": {
+          "ExpressionBody": {
+           "inputTypes": {
+            "flag": {
+             "Reference": {
+              "fqname": "morphir/SDK:basics#bool"
+             }
+            },
+            "first": {
+             "Reference": {
+              "fqname": "acme/example:models#decision"
+             }
+            },
+            "second": {
+             "Reference": {
+              "fqname": "acme/example:models#decision"
+             }
+            }
+           },
+           "outputType": {
+            "Reference": {
+             "fqname": "acme/example:models#decision"
+            }
+           },
+           "body": {
+            "IfThenElse": {
+             "condition": {
+              "Variable": {
+               "name": "flag"
+              }
+             },
+             "then": {
+              "Variable": {
+               "name": "first"
+              }
+             },
+             "else": {
+              "Variable": {
+               "name": "second"
+              }
+             }
+            }
+           }
+          }
+         }
+        }
+       }
+      }
+     }
+    }
+   }
+  }
+ }
+}
diff --git a/tests/tools/test_cli.py b/tests/tools/test_cli.py
index 2e8be39f..e35efca4 100644
--- a/tests/tools/test_cli.py
+++ b/tests/tools/test_cli.py
@@ -326,3 +326,53 @@ def test_string_legacy_version_is_invalid(self, tmp_path: Path) -> None:
         result = run("ir", "inspect", write(tmp_path, "x.json", doc))
         assert result.exit_code == 1
         assert d.INVALID_FORMAT_VERSION_SYNTAX in result.stderr
+
+
+class TestConvertSpelling:
+    """``ir convert --to v4`` writes the compact spelling unless asked otherwise."""
+
+    def test_default_is_compact_and_inspects(self, tmp_path: Path) -> None:
+        out = tmp_path / "compact.json"
+        assert run("ir", "convert", VALUE_TREE, "--to", "v4", "-o", out).exit_code == 0
+        text = out.read_text()
+        assert '{"Reference":{"fqname"' not in text
+        assert '"morphir/SDK:basics#int"' in text
+        inspected = run("ir", "inspect", out)
+        assert inspected.exit_code == 0
+        assert "format: 4.0.0" in inspected.output
+
+    def test_expanded_on_request_decodes_to_the_same_model(
+        self, tmp_path: Path
+    ) -> None:
+        from morphir.ir.v4 import codec
+
+        compact, expanded = tmp_path / "c.json", tmp_path / "e.json"
+        assert (
+            run("ir", "convert", VALUE_TREE, "--to", "v4", "-o", compact).exit_code == 0
+        )
+        result = run(
+            "ir", "convert", VALUE_TREE, "--to", "v4",
+            "--v4-spelling", "expanded", "-o", expanded,
+        )  # fmt: skip
+        assert result.exit_code == 0, result.output
+        assert '{"Reference":{"fqname"' in expanded.read_text()
+        assert codec.decode_versioned_distribution(
+            compact.read_text()
+        ) == codec.decode_versioned_distribution(expanded.read_text())
+
+    def test_unknown_spelling_is_a_usage_error(self, tmp_path: Path) -> None:
+        result = run(
+            "ir", "convert", VALUE_TREE, "--to", "v4",
+            "--v4-spelling", "short", "-o", tmp_path / "x.json",
+        )  # fmt: skip
+        assert result.exit_code == 2
+        assert not (tmp_path / "x.json").exists()
+
+    def test_spelling_does_not_change_v3_output(
+        self, v4_file: Path, tmp_path: Path
+    ) -> None:
+        plain, spelled = tmp_path / "p.json", tmp_path / "s.json"
+        assert run("ir", "convert", v4_file, "--to", "v3", "-o", plain).exit_code == 0
+        args = ["--to", "v3", "--v4-spelling", "expanded", "-o", spelled]
+        assert run("ir", "convert", v4_file, *args).exit_code == 0
+        assert plain.read_text() == spelled.read_text()
diff --git a/tests/tools/test_python_crosscodec.py b/tests/tools/test_python_crosscodec.py
index f72095c0..8e36102d 100644
--- a/tests/tools/test_python_crosscodec.py
+++ b/tests/tools/test_python_crosscodec.py
@@ -104,7 +104,8 @@ def test_python_encoded_v4_generates_like_rust_encoded_v4(self) -> None:
             )["ir"]
         )
         expanded = v4_codec.encode_versioned_distribution(
-            direct.distribution  # type: ignore[arg-type]
+            direct.distribution,  # type: ignore[arg-type]
+            spelling=v4_codec.Spelling.EXPANDED,
         )
         assert native != expanded
         assert v4_codec.decode_versioned_distribution(native) == direct.distribution
diff --git a/tests/unit/ir/test_v4_compact.py b/tests/unit/ir/test_v4_compact.py
index 4480bdae..cffe9f03 100644
--- a/tests/unit/ir/test_v4_compact.py
+++ b/tests/unit/ir/test_v4_compact.py
@@ -30,6 +30,7 @@
 from morphir.ir.v4 import type_spec as ts
 from morphir.ir.v4 import value as v
 from morphir.ir.v4.access_controlled import Private, Public
+from morphir.ir.v4.codec import Spelling
 from morphir.ir.v4.distribution import (
     ApplicationDistribution,
     EntryPointKind,
@@ -258,7 +259,7 @@ class TestTypeSpellings:
     def test_compact_reads_as_expanded(self, compact: Json, expanded: Json) -> None:
         decoded = codec.decode_type(compact)
         assert decoded == codec.decode_type(expanded)
-        assert codec.encode_type(decoded) == expanded
+        assert codec.encode_type(decoded, spelling=Spelling.EXPANDED) == expanded
 
     def test_compact_model(self) -> None:
         assert codec.decode_type("morphir/SDK:basics#int") == INT
@@ -687,7 +688,7 @@ class TestValueSpellings:
     def test_compact_reads_as_expanded(self, compact: Json, expanded: Json) -> None:
         decoded = codec.decode_value(compact)
         assert decoded == codec.decode_value(expanded)
-        assert codec.encode_value(decoded) == expanded
+        assert codec.encode_value(decoded, spelling=Spelling.EXPANDED) == expanded
 
     def test_compact_model(self) -> None:
         assert codec.decode_value(42) == v.LiteralValue(VA, lit.IntegerLiteral(42))
@@ -899,7 +900,7 @@ class TestPatternSpellings:
     def test_compact_reads_as_expanded(self, compact: Json, expanded: Json) -> None:
         decoded = codec.decode_pattern(compact)
         assert decoded == codec.decode_pattern(expanded)
-        assert codec.encode_pattern(decoded) == expanded
+        assert codec.encode_pattern(decoded, spelling=Spelling.EXPANDED) == expanded
 
     @pytest.mark.parametrize(
         ("bad", "code"),
@@ -1445,7 +1446,7 @@ def test_adt_fixture(self) -> None:
     @pytest.mark.parametrize("name", ["modules-v4.json", "adt-v4.json"])
     def test_fixture_round_trips_through_the_expanded_writer(self, name: str) -> None:
         dist = library(COMPILER / name)
-        encoded = codec.encode_versioned_distribution(dist)
+        encoded = codec.encode_versioned_distribution(dist, spelling=Spelling.EXPANDED)
         assert codec.decode_versioned_distribution(json.dumps(encoded)) == dist
         assert encoded != load(COMPILER / name)
 
diff --git a/tests/unit/ir/test_v4_compact_writer.py b/tests/unit/ir/test_v4_compact_writer.py
new file mode 100644
index 00000000..692ea9fd
--- /dev/null
+++ b/tests/unit/ir/test_v4_compact_writer.py
@@ -0,0 +1,285 @@
+"""The v4 writer: compact canonical spelling, flattened documentation, selection.
+
+The compact forms follow morphir-core 0.2.0, the reference writer at the same
+finos/morphir v4 JSON profile (``serde_v4.rs``): a node without attributes is
+written in its shortest schema-valid form, a node with attributes keeps the
+expanded spelling with ``attributes`` first, and ``doc`` is flattened first
+beside the documented node (decision 0010).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from morphir.ir import diagnostics as d
+from morphir.ir.diagnostics import DiagnosticError
+from morphir.ir.v4 import codec
+from morphir.ir.v4 import literal as lit
+from morphir.ir.v4 import type as t
+from morphir.ir.v4 import value as v
+from morphir.ir.v4.codec import Spelling
+from morphir.ir.v4.fqname import FQName
+from morphir.ir.v4.name import Name
+from morphir.ir.v4.path import Path as IrPath
+
+FIXTURES = Path(__file__).resolve().parents[2] / "fixtures" / "ir"
+COMPILER = FIXTURES / "python-compiler"
+UPSTREAM = FIXTURES / "v4"
+
+INT = FQName(
+    IrPath((Name(("morphir",)), Name(("s", "d", "k")))),
+    IrPath((Name(("basics",)),)),
+    Name(("int",)),
+)
+LIST = FQName(INT.package_path, IrPath((Name(("list",)),)), Name(("list",)))
+NO_TYPE = t.TypeAttributes()
+NO_VALUE = v.ValueAttributes()
+LOCATED = t.TypeAttributes(source=t.SourceLocation(1, 2, 3, 4))
+
+
+def name(*words: str) -> Name:
+    return Name(words)
+
+
+@pytest.mark.parametrize("fixture", ["modules-v4.json", "adt-v4.json"])
+def test_compiler_output_re_encodes_byte_for_byte(fixture: str) -> None:
+    text = (COMPILER / fixture).read_text()
+    original = json.loads(text)
+    encoded = codec.encode_versioned_distribution(
+        codec.decode_versioned_distribution(text)
+    )
+    assert json.dumps(encoded) == json.dumps(original)
+
+
+@pytest.mark.parametrize("fixture", ["modules-v4", "adt-v4"])
+def test_expanded_spelling_is_unchanged(fixture: str) -> None:
+    # The golden files hold the writer's output before the compact spelling.
+    model = codec.decode_versioned_distribution(
+        (COMPILER / f"{fixture}.json").read_text()
+    )
+    golden = json.loads((COMPILER / f"{fixture}.expanded.json").read_text())
+    encoded = codec.encode_versioned_distribution(model, spelling=Spelling.EXPANDED)
+    assert json.dumps(encoded) == json.dumps(golden)
+
+
+@pytest.mark.parametrize(
+    ("tpe", "expected"),
+    [
+        (t.Variable(NO_TYPE, name("a")), "a"),
+        (t.Reference(NO_TYPE, INT, []), "morphir/SDK:basics#int"),
+        (
+            t.Reference(NO_TYPE, LIST, [t.Variable(NO_TYPE, name("a"))]),
+            {"Reference": ["morphir/SDK:list#list", "a"]},
+        ),
+        (
+            t.Tuple(NO_TYPE, [t.Reference(NO_TYPE, INT, []), t.Unit(NO_TYPE)]),
+            {"Tuple": ["morphir/SDK:basics#int", {"Unit": {}}]},
+        ),
+        (
+            t.Function(
+                NO_TYPE, t.Variable(NO_TYPE, name("a")), t.Reference(NO_TYPE, INT, [])
+            ),
+            {
+                "Function": {
+                    "parameterType": "a",
+                    "returnType": "morphir/SDK:basics#int",
+                }
+            },
+        ),
+        (
+            t.Record(NO_TYPE, [t.Field(name("count"), t.Reference(NO_TYPE, INT, []))]),
+            {"Record": {"fields": {"count": "morphir/SDK:basics#int"}}},
+        ),
+    ],
+)
+def test_compact_type_forms(tpe: t.Type, expected: Any) -> None:
+    assert codec.encode_type(tpe) == expected
+    assert codec.decode_type(codec.encode_type(tpe)) == tpe
+
+
+def test_a_type_with_attributes_keeps_the_expanded_spelling() -> None:
+    located = t.Reference(LOCATED, INT, [t.Variable(NO_TYPE, name("a"))])
+    encoded = codec.encode_type(located)
+    assert list(encoded["Reference"]) == ["attributes", "fqname", "args"]
+    assert encoded["Reference"]["args"] == ["a"]
+    assert codec.decode_type(encoded) == located
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        (
+            v.LiteralValue(NO_VALUE, lit.IntegerLiteral(42)),
+            {"Literal": {"IntegerLiteral": 42}},
+        ),
+        (
+            v.LiteralValue(NO_VALUE, lit.StringLiteral("x")),
+            {"Literal": {"StringLiteral": "x"}},
+        ),
+        (v.Variable(NO_VALUE, name("flag")), {"Variable": "flag"}),
+        (v.Reference(NO_VALUE, INT), {"Reference": "morphir/SDK:basics#int"}),
+        (v.Constructor(NO_VALUE, INT), {"Constructor": "morphir/SDK:basics#int"}),
+        (v.FieldFunction(NO_VALUE, name("count")), {"FieldFunction": "count"}),
+        (
+            v.Tuple(NO_VALUE, [v.Variable(NO_VALUE, name("a")), v.Unit(NO_VALUE)]),
+            {"Tuple": [{"Variable": "a"}, {"Unit": {}}]},
+        ),
+        (
+            v.List(NO_VALUE, [v.LiteralValue(NO_VALUE, lit.BoolLiteral(True))]),
+            {"List": [{"Literal": {"BoolLiteral": True}}]},
+        ),
+        (
+            v.Apply(
+                NO_VALUE, v.Reference(NO_VALUE, INT), v.Variable(NO_VALUE, name("a"))
+            ),
+            {
+                "Apply": {
+                    "function": {"Reference": "morphir/SDK:basics#int"},
+                    "argument": {"Variable": "a"},
+                }
+            },
+        ),
+    ],
+)
+def test_compact_value_forms(value: v.Value, expected: Any) -> None:
+    assert codec.encode_value(value) == expected
+    assert codec.decode_value(codec.encode_value(value)) == value
+
+
+def test_compact_pattern_forms() -> None:
+    pattern = v.TuplePattern(
+        NO_VALUE,
+        [
+            v.LiteralPattern(NO_VALUE, lit.IntegerLiteral(1)),
+            v.WildcardPattern(NO_VALUE),
+        ],
+    )
+    encoded = codec.encode_pattern(pattern)
+    assert encoded == {
+        "TuplePattern": [
+            {"LiteralPattern": {"IntegerLiteral": 1}},
+            {"WildcardPattern": {}},
+        ]
+    }
+    assert codec.decode_pattern(encoded) == pattern
+
+
+def test_a_value_with_attributes_keeps_the_expanded_spelling() -> None:
+    typed = v.ValueAttributes(inferred_type=t.Reference(NO_TYPE, INT, []))
+    value = v.Variable(typed, name("a"))
+    encoded = codec.encode_value(value)
+    assert list(encoded["Variable"]) == ["attributes", "name"]
+    assert encoded["Variable"]["attributes"]["inferredType"] == "morphir/SDK:basics#int"
+    assert codec.decode_value(encoded) == value
+
+
+COMPACT_TAGS = {
+    "Literal",
+    "Variable",
+    "Reference",
+    "Constructor",
+    "FieldFunction",
+    "Tuple",
+    "List",
+    "TuplePattern",
+    "LiteralPattern",
+}
+
+
+def compact_nodes(json_value: Any, path: tuple[Any, ...] = ()) -> list[tuple[Any, ...]]:
+    """Paths of wrappers whose payload is not an expanded object."""
+    found: list[tuple[Any, ...]] = []
+    if isinstance(json_value, dict):
+        for key, item in json_value.items():
+            if (
+                key in COMPACT_TAGS
+                and len(json_value) == 1
+                and not isinstance(item, dict)
+            ):
+                found.append((*path, key))
+            found.extend(compact_nodes(item, (*path, key)))
+    elif isinstance(json_value, list):
+        for index, item in enumerate(json_value):
+            found.extend(compact_nodes(item, (*path, index)))
+    return found
+
+
+@pytest.mark.parametrize(
+    "fixture",
+    [
+        COMPILER / "modules-v4.json",
+        COMPILER / "adt-v4.json",
+        UPSTREAM / "finos-books-and-records-example.json",
+    ],
+)
+def test_expanded_output_has_no_compact_node(fixture: Path) -> None:
+    model = codec.decode_versioned_distribution(fixture.read_text())
+    expanded = codec.encode_versioned_distribution(model, spelling=Spelling.EXPANDED)
+    assert compact_nodes(expanded) == []
+    compact = codec.encode_versioned_distribution(model)
+    assert compact_nodes(compact) != []
+    assert codec.decode_versioned_distribution(json.dumps(expanded)) == model
+    assert codec.decode_versioned_distribution(json.dumps(compact)) == model
+
+
+def test_the_selection_applies_only_to_its_call() -> None:
+    tpe = t.Reference(NO_TYPE, INT, [])
+    assert codec.encode_type(tpe, spelling=Spelling.EXPANDED) == {
+        "Reference": {"fqname": "morphir/SDK:basics#int"}
+    }
+    assert codec.encode_type(tpe) == "morphir/SDK:basics#int"
+
+
+def test_documentation_is_flattened_first() -> None:
+    document = json.loads((COMPILER / "modules-v4.json").read_text())
+    modules = document["distribution"]["Library"]["def"]["modules"]
+    point = modules["models"]["Public"]["types"]["point"]["Public"]
+    modules["models"]["Public"]["types"]["point"]["Public"] = {
+        "doc": "A point.",
+        **point,
+    }
+    choose = modules["rules"]["Public"]["values"]["select-decision"]["Public"]
+    modules["rules"]["Public"]["values"]["select-decision"]["Public"] = {
+        "value": choose,
+        "doc": "Choose one.",
+    }
+    model = codec.decode_versioned_distribution(json.dumps(document))
+    for spelling in Spelling:
+        encoded = codec.encode_versioned_distribution(model, spelling=spelling)
+        documented = [
+            node for node in _objects(encoded) if "doc" in node and "types" not in node
+        ]
+        assert len(documented) == 2
+        for node in documented:
+            # Decision 0010: `doc` first, beside the node's own members.
+            assert next(iter(node)) == "doc"
+            assert "value" not in node
+        assert codec.decode_versioned_distribution(json.dumps(encoded)) == model
+
+
+def _objects(json_value: Any) -> list[dict[str, Any]]:
+    found: list[dict[str, Any]] = []
+    if isinstance(json_value, dict):
+        found.append(json_value)
+        for item in json_value.values():
+            found.extend(_objects(item))
+    elif isinstance(json_value, list):
+        for item in json_value:
+            found.extend(_objects(item))
+    return found
+
+
+def test_a_documented_node_that_is_not_an_object_is_refused() -> None:
+    def encode_string(value: str, _loc: tuple[Any, ...]) -> Any:
+        return value
+
+    run = codec._encode_documented(encode_string)
+    from morphir.ir.v4.documented import Documented
+
+    with pytest.raises(DiagnosticError) as error:
+        run(Documented("text", "not an object"), ())
+    assert error.value.codes == (d.NO_V4_SPELLING,)
diff --git a/tests/unit/ir/test_v4_upstream.py b/tests/unit/ir/test_v4_upstream.py
index b22fed15..8265099c 100644
--- a/tests/unit/ir/test_v4_upstream.py
+++ b/tests/unit/ir/test_v4_upstream.py
@@ -6,6 +6,8 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 import pytest
 
 from morphir.ir import diagnostics as d
@@ -30,6 +32,16 @@
 from morphir.ir.v4.name import Name
 from morphir.ir.v4.path import Path
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+@pytest.fixture(autouse=True)
+def _expanded_spelling() -> Iterator[None]:
+    """The upstream kit cases quote the expanded spelling, so encode with it."""
+    with codec.use_spelling(codec.Spelling.EXPANDED):
+        yield
+
 
 def n(*words: str) -> Name:
     return Name(words)

From e66a00dff9cee2a04885876795c203097b4ca07a Mon Sep 17 00:00:00 2001
From: Damian Reeves <957246+DamianReeves@users.noreply.github.com>
Date: Tue, 27 Oct 2026 21:24:01 -0500
Subject: [PATCH 3/3] fix(ir): keep the Variable tag for type variables outside
 the bare grammar

The schema's bare type-variable string is lowercase only, so names such
as USD, item-USD or 123 were written in a form the reader rejects. Write
them as {"Variable": name}, which is still compact and reads back.
---
 packages/morphir/src/morphir/ir/v4/codec.py |  5 ++++-
 tests/unit/ir/test_v4_compact_writer.py     | 13 +++++++++++++
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/packages/morphir/src/morphir/ir/v4/codec.py b/packages/morphir/src/morphir/ir/v4/codec.py
index b308175c..6990ae4c 100644
--- a/packages/morphir/src/morphir/ir/v4/codec.py
+++ b/packages/morphir/src/morphir/ir/v4/codec.py
@@ -895,8 +895,11 @@ def _encode_type(tpe: t.Type, loc: Location) -> Json:
     def node(tag: str, members: dict[str, Json]) -> Json:
         if _compact(attrs):
             match tag:
-                case "Variable":
+                case "Variable" if _TYPE_VARIABLE_STRING.fullmatch(members["name"]):
                     return members["name"]
+                case "Variable":
+                    # The bare string grammar is lowercase only; keep the tag.
+                    return {"Variable": members["name"]}
                 case "Reference" if "args" in members:
                     return {"Reference": [members["fqname"], *members["args"]]}
                 case "Reference":
diff --git a/tests/unit/ir/test_v4_compact_writer.py b/tests/unit/ir/test_v4_compact_writer.py
index 692ea9fd..73f174fc 100644
--- a/tests/unit/ir/test_v4_compact_writer.py
+++ b/tests/unit/ir/test_v4_compact_writer.py
@@ -283,3 +283,16 @@ def encode_string(value: str, _loc: tuple[Any, ...]) -> Any:
     with pytest.raises(DiagnosticError) as error:
         run(Documented("text", "not an object"), ())
     assert error.value.codes == (d.NO_V4_SPELLING,)
+
+
+@pytest.mark.parametrize("words", [("u", "s", "d"), ("item", "u", "s", "d"), ("123",)])
+def test_a_variable_outside_the_bare_string_grammar_keeps_its_tag(
+    words: tuple[str, ...],
+) -> None:
+    # The schema's bare type-variable string is lowercase only; other valid
+    # names need {"Variable": name} to read back.
+    tpe = t.Variable(NO_TYPE, Name(words))
+    encoded = codec.encode_type(tpe)
+    assert isinstance(encoded, dict)
+    assert set(encoded) == {"Variable"}
+    assert codec.decode_type(encoded) == tpe