Merge pull request #202 from rustledger/feat/192-expand-pads-drop-jsonrpc

feat(rustledger): adopt v0.18.0 engine (ledger@3.1.0), expand pads, drop JSON-RPC backend

Author: robcohen

.github/workflows/desktop-release.yml

@@ -40,7 +40,10 @@ jobs:
           - os: ubuntu-22.04
             target: x86_64-unknown-linux-gnu
             sidecar_name: rustfava-server-x86_64-unknown-linux-gnu
-          - os: macos-latest
+          # PyInstaller cannot cross-compile: it emits a binary for the
+          # runner's own arch. macos-latest is now Apple Silicon, so the x64
+          # sidecar must build on a real Intel runner (issue #193).
+          - os: macos-13
             target: x86_64-apple-darwin
             sidecar_name: rustfava-server-x86_64-apple-darwin
           - os: macos-14
@@ -66,13 +69,17 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
 
-      - name: Download rustledger WASM from release
+      - name: Download rustledger component WASM from release
         shell: bash
+        # The in-process WASI Preview 2 component is the engine; the frozen app
+        # bundles it (see contrib/pyinstaller_spec.spec) so it need not download
+        # at first run. The legacy rustledger-ffi-wasi-*.wasm is no longer
+        # shipped upstream (rustledger #1419).
         run: |
           gh release download ${{ steps.rustledger-tag.outputs.tag }} \
             --repo ${{ env.RUSTLEDGER_REPO }} \
-            --pattern "rustledger-ffi-wasi-*.wasm" \
-            --output src/rustfava/rustledger/rustledger-wasi.wasm
+            --pattern "rustledger-ffi-component-*.wasm" \
+            --output src/rustfava/rustledger/rustledger_ffi_component.wasm
         env:
           GH_TOKEN: ${{ github.token }}
 
@@ -115,6 +122,13 @@ jobs:
               print(f'Compiled {po} -> {mo}')
           "
 
+      - name: Set RUSTFAVA_VERSION from tag
+        # The spec bakes this into rustfava/_version.py so the frozen binary
+        # reports the real version without dist-info metadata (issue #191).
+        if: startsWith(github.ref, 'refs/tags/')
+        shell: bash
+        run: echo "RUSTFAVA_VERSION=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_ENV"
+
       - name: Build sidecar with PyInstaller
         shell: bash
         run: |
@@ -130,6 +144,24 @@ jobs:
         run: |
           move dist\rustfava.exe dist\${{ matrix.sidecar_name }}
 
+      - name: Verify sidecar architecture (macOS)
+        if: runner.os == 'macOS'
+        shell: bash
+        run: |
+          BIN="dist/${{ matrix.sidecar_name }}"
+          file "$BIN"
+          case "${{ matrix.target }}" in
+            x86_64-*) EXPECT="x86_64" ;;
+            aarch64-*) EXPECT="arm64" ;;
+            *) echo "::error::Unknown macOS target ${{ matrix.target }}"; exit 1 ;;
+          esac
+          # Use `file -b` (no filename) so the sidecar_name — which itself
+          # contains "x86_64"/"aarch64" — can't false-match the grep.
+          if ! file -b "$BIN" | grep -qw "$EXPECT"; then
+            echo "::error::Sidecar arch mismatch: expected $EXPECT for ${{ matrix.target }}, got: $(file -b "$BIN")"
+            exit 1
+          fi
+
       - name: Upload sidecar artifact
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
@@ -214,7 +246,9 @@ jobs:
           - os: ubuntu-22.04
             target: x86_64-unknown-linux-gnu
             sidecar_name: rustfava-server-x86_64-unknown-linux-gnu
-          - os: macos-latest
+          # Intel runner: builds x86_64 natively so the smoke test can launch
+          # the binary (an arm64 runner has no Rosetta by default), issue #193.
+          - os: macos-13
             target: x86_64-apple-darwin
             sidecar_name: rustfava-server-x86_64-apple-darwin
           - os: macos-14
@@ -313,6 +347,26 @@ jobs:
           ls -la "$APP_PATH" || { echo "App bundle not found!"; exit 1; }
           file "$BINARY"
 
+          # Verify the bundled sidecar matches the target arch (issue #193).
+          # Tauri strips the target triple, so the bundled name is plain
+          # `rustfava-server` (no arch substring to confuse the grep).
+          SIDECAR="$APP_PATH/Contents/MacOS/rustfava-server"
+          if [ -f "$SIDECAR" ]; then
+            file "$SIDECAR"
+            case "${{ matrix.target }}" in
+              x86_64-*) EXPECT="x86_64" ;;
+              aarch64-*) EXPECT="arm64" ;;
+              *) echo "::error::Unknown macOS target ${{ matrix.target }}"; exit 1 ;;
+            esac
+            if ! file -b "$SIDECAR" | grep -qw "$EXPECT"; then
+              echo "::error::Bundled sidecar arch mismatch: expected $EXPECT for ${{ matrix.target }}, got: $(file -b "$SIDECAR")"
+              exit 1
+            fi
+          else
+            echo "::error::Bundled sidecar not found at $SIDECAR"
+            exit 1
+          fi
+
           # Run binary directly to capture stdout/stderr and panic backtrace
           echo "=== Launching with RUST_BACKTRACE=full ==="
           RUST_BACKTRACE=full RUST_LOG=debug "$BINARY" > /tmp/app.log 2>&1 &

README.md

@@ -40,17 +40,9 @@ Download the latest release for your platform from the [Releases page](https://g
 | **Windows** | `.exe` installer or `.msi` |
 | **Linux** | `.AppImage`, `.deb`, `.rpm`, or `.tar.gz` |
 
-> **Backends**: rustfava runs the rustledger engine as an in-process WebAssembly
-> component, so the `wasmtime` Python package ships as a dependency and the
-> default backend works out of the box — no separate install needed.
->
-> To opt back into the legacy JSON-RPC engine
-> (`RUSTFAVA_RUSTLEDGER_BACKEND=jsonrpc`), you must install the
-> [wasmtime](https://wasmtime.dev/) **CLI** separately (it is *not* a Python
-> dependency); the component backend does not need it:
-> ```bash
-> curl https://wasmtime.dev/install.sh -sSf | bash
-> ```
+> **Engine**: rustfava runs the rustledger engine as an in-process WebAssembly
+> component, so the `wasmtime` Python package ships as a dependency and works
+> out of the box — no separate install needed.
 
 ### Other Installation Methods
 

contrib/pyinstaller_spec.spec

@@ -48,8 +48,10 @@ if translations_dir.exists():
         rel_path = f.relative_to(rustfava_dir)
         datas.append((str(f), f"rustfava/{rel_path.parent}"))
 
-# WASM file for rustledger
-wasm_file = rustfava_dir / "rustledger" / "rustledger-wasi.wasm"
+# Rustledger engine: the in-process WASI Preview 2 component. Bundled when
+# present so the frozen app does not have to download it at first run (the
+# component_engine cache path is read-only inside the PyInstaller bundle).
+wasm_file = rustfava_dir / "rustledger" / "rustledger_ffi_component.wasm"
 if wasm_file.exists():
     datas.append((str(wasm_file), "rustfava/rustledger"))
 

docs/deployment.md

@@ -2,26 +2,15 @@
 
 There are several ways to deploy rustfava depending on your needs.
 
-## Backends
-
-rustfava runs the rustledger engine in one of two ways, selected by the
-`RUSTFAVA_RUSTLEDGER_BACKEND` environment variable:
-
-- **`component`** (default) — runs the rustledger WebAssembly component
-  in-process via the `wasmtime` Python package, which is installed
-  automatically as a dependency. Nothing extra to set up.
-- **`jsonrpc`** (`json-rpc`/`json`) — the legacy engine, which shells out to the
-  `wasmtime` **CLI** over JSON-RPC. The CLI is **not** a Python dependency, so
-  you must install it separately for this backend:
-
-  ```bash
-  curl https://wasmtime.dev/install.sh -sSf | bash
-  ```
-
-If `RUSTFAVA_RUSTLEDGER_BACKEND` is unset (or set to anything other than a
-JSON-RPC alias) the component backend is used. As a safety net, if the
-`wasmtime` package can't be imported, rustfava falls back to the JSON-RPC engine
-— which then requires the CLI above.
+## Engine
+
+rustfava runs the rustledger engine as a WebAssembly component in-process via
+the `wasmtime` Python package, which is installed automatically as a
+dependency. Nothing extra to set up.
+
+> The legacy JSON-RPC engine (which shelled out to the `wasmtime` CLI) was
+> removed in rustfava 1.31 after its embedding surface was retired upstream;
+> `RUSTFAVA_RUSTLEDGER_BACKEND` is no longer used.
 
 ## Desktop App
 

frontend/test/end-to-end-validation.test.ts

@@ -67,5 +67,7 @@ test("validate journal", async () => {
   const res = array(entryValidator)(data);
   ok(res.is_ok);
   const entries = res.unwrap();
-  equal(entries.length, 23);
+  // 24 (was 23): the example ledger's `pad` now materializes a Padding
+  // transaction in the journal (rustfava #192, engine expand-pads).
+  equal(entries.length, 24);
 });

src/rustfava/rustledger/__init__.py

@@ -7,7 +7,6 @@
 from __future__ import annotations
 
 from rustfava.rustledger.backend import get_engine
-from rustfava.rustledger.engine import RustledgerEngine
 from rustfava.rustledger.loader import load_string
 from rustfava.rustledger.loader import load_uncached
 
@@ -25,7 +24,6 @@ def is_encrypted_file(path: str) -> bool:
 
 
 __all__ = [
-    "RustledgerEngine",
     "get_engine",
     "is_encrypted_file",
     "load_string",

src/rustfava/rustledger/backend.py

@@ -1,8 +1,9 @@
-"""Select the rustledger engine backend.
+"""Resolve the rustledger engine backend.
 
 The in-process component engine (WASI Preview 2 / Component Model, rustledger
-#1384) is the **default**; set ``RUSTFAVA_RUSTLEDGER_BACKEND=jsonrpc`` to opt
-back into the legacy JSON-RPC engine. The flip is tracked in #173.
+#1384) is the only backend. The legacy wasmtime-CLI JSON-RPC engine was removed
+once its wasip1 embedding surface was retired upstream (rustledger #1419 /
+rustfava #173), so ``RUSTFAVA_RUSTLEDGER_BACKEND`` is no longer consulted.
 
 This lives in its own module — not the package ``__init__`` — so call sites can
 import :func:`get_engine` at module level without a circular import through the
@@ -11,44 +12,25 @@
 
 from __future__ import annotations
 
-import os
-import shutil
 from typing import Any
 
-from rustfava.rustledger.engine import RustledgerEngine
 from rustfava.rustledger.engine import RustledgerError
 
-# Values of ``RUSTFAVA_RUSTLEDGER_BACKEND`` that select the legacy engine.
-_JSONRPC_ALIASES = frozenset({"jsonrpc", "json-rpc", "json"})
-
 
 def get_engine() -> Any:
-    """Return the engine selected by ``RUSTFAVA_RUSTLEDGER_BACKEND``.
-
-    The in-process component engine is the default; ``jsonrpc`` (or
-    ``json-rpc``/``json``) selects the legacy JSON-RPC engine.
-    """
-    backend = os.environ.get("RUSTFAVA_RUSTLEDGER_BACKEND", "").lower()
-    if backend in _JSONRPC_ALIASES:
-        return RustledgerEngine.get_instance()
+    """Return the in-process rustledger component engine."""
     try:
         from rustfava.rustledger.component_engine import (  # noqa: PLC0415
             get_component_engine,
         )
     except ImportError as exc:
-        # The default component backend needs the `wasmtime` Python package.
-        # The legacy JSON-RPC engine instead needs an external `wasmtime` CLI
-        # binary that most users don't have — silently falling back to it just
-        # turns "component unavailable" into a cryptic "wasmtime not found" /
-        # "Empty response" later (rustfava #136/#120). Only fall back if the
-        # CLI is actually present; otherwise fail with an actionable message.
-        if shutil.which("wasmtime"):
-            return RustledgerEngine.get_instance()
+        # The component backend needs the `wasmtime` Python package, a required
+        # rustfava dependency. A missing import means a broken install rather
+        # than a configuration choice — fail with an actionable message.
         msg = (
             "The rustledger component backend is unavailable: the `wasmtime` "
             "package could not be imported. Reinstall rustfava (wasmtime is a "
-            "required dependency), or install the wasmtime CLI and set "
-            "RUSTFAVA_RUSTLEDGER_BACKEND=jsonrpc."
+            "required dependency)."
         )
         raise RustledgerError(msg) from exc
     return get_component_engine()

src/rustfava/rustledger/component_engine.py

@@ -51,11 +51,15 @@
 from rustfava.rustledger.engine import RUSTLEDGER_VERSION
 from rustfava.rustledger.engine import RustledgerError
 
-# The four exported WIT interfaces (package ``rustledger:ledger@2.1.0``).
-_LEDGER = "rustledger:ledger/ledger@2.1.0"
-_BUILDER = "rustledger:ledger/builder@2.1.0"
-_UTIL = "rustledger:ledger/util@2.1.0"
-_FORMAT = "rustledger:ledger/format@2.1.0"
+# The exported WIT interfaces of package ``rustledger:ledger``. The interface
+# IDs embed the full WIT package version (independent of the rustledger release
+# version), so a WIT bump means updating ``_WIT_VERSION`` here — a mismatch
+# makes ``get_export_index`` return ``None`` and every call fail.
+_WIT_VERSION = "3.1.0"
+_LEDGER = f"rustledger:ledger/ledger@{_WIT_VERSION}"
+_BUILDER = f"rustledger:ledger/builder@{_WIT_VERSION}"
+_UTIL = f"rustledger:ledger/util@{_WIT_VERSION}"
+_FORMAT = f"rustledger:ledger/format@{_WIT_VERSION}"
 
 
 _COMPONENT_WASM_URL = (
@@ -616,14 +620,23 @@ def version(self) -> str:
         """Return the component's ``api_version`` string (e.g. ``"2.1"``)."""
         return self._call(_LEDGER, "version", [])
 
-    def load(self, source: str, filename: str = "<stdin>") -> dict[str, Any]:
+    def load(
+        self,
+        source: str,
+        filename: str = "<stdin>",
+        *,
+        expand_pads: bool = False,
+    ) -> dict[str, Any]:
         """Parse + book ``source``; returns entries/errors/options/....
 
-        ``filename`` is recorded as the directives' source location (the WIT
-        ``load`` takes it, matching the JSON-RPC engine).
+        ``filename`` is the directives' source location. When ``expand_pads``
+        is true the engine materializes ``pad`` directives into synthesized
+        ``Padding`` transactions (sorted by date, no source location) so
+        balance-computing consumers see padded balances; the default keeps the
+        source-faithful stream (rustledger #1628 / rustfava #192).
         """
         self._ensure_version()
-        return self._call(_LEDGER, "load", [source, filename])
+        return self._call(_LEDGER, "load", [source, filename, expand_pads])
 
     def query(self, source: str, query_string: str) -> dict[str, Any]:
         """Run a BQL query over ``source``; returns columns/rows/errors."""
@@ -656,9 +669,15 @@ def load_full(
         *,
         allow_unrestricted_includes: bool = False,
         plugins: list[str] | None = None,
+        expand_pads: bool = False,
     ) -> dict[str, Any]:
         """Load a file (resolving includes/plugins) via the component.
 
+        When ``expand_pads`` is true the engine materializes ``pad`` directives
+        into synthesized ``Padding`` transactions so balance-computing
+        consumers see padded balances; the default keeps the source-faithful
+        stream (rustledger #1628 / rustfava #192).
+
         Unlike the source-based calls this needs filesystem access, so it runs
         on a fresh instance with the file's directory pre-opened into the WASI
         sandbox at ``/work`` and the path rewritten accordingly.
@@ -681,7 +700,12 @@ def load_full(
             inst,
             _LEDGER,
             "load-file",
-            [guest_path, allow_unrestricted_includes, plugins or []],
+            [
+                guest_path,
+                allow_unrestricted_includes,
+                plugins or [],
+                expand_pads,
+            ],
         )
         # The component sees files under the WASI pre-open mount (``/work``),
         # so the directives it returns carry guest paths in ``meta.filename``