Skip to content

Release v0.2.0

Choose a tag to compare

@homer6 homer6 released this 17 Oct 23:59
· 179 commits to main since this release
1bf3d41

Released: 2026-10-17 · Branch: dev, promoted to main · Previous:
v0.1.0 (2026-10-12).

liquid is a version control system, build system, package manager, artifact service and
runtime in one program: a C++26 library, libliquid, and a liquid command-line binary that
is a thin client of it.

The library and the binary are the v0.1.0 source. Between v0.1.0 and this release, one
pull request merged, and it changed only CLAUDE.md. This release adds a test that holds the
version in its three places, moves the release procedure to dev → main, and records where
liquid runs and what is known to be broken as of 2026-10-17. Lake v0.2.0 shipped the same day
on liquid v0.1.0.

Five days after v0.1.0, this is not a release after a long gap, so the page lists what changed
and does not repeat the inventory. Everything liquid implements, by area, and all 80 commands
are on the v0.1.0 page
, and they are unchanged: the CLI reference generated from
the v0.2.0 binary is identical to docs/reference/cli/ (80 commands).

Measured Value
Merged pull requests since v0.1.0 1 (#359, CLAUDE.md only) plus this release's
Files changed under src/ and include/ 2: the version in src/version.cpp and include/liquid/version.hpp
Commands in the generated CLI reference 80, unchanged
Tests, macOS 747 run, 735 passed, 0 failed, 12 skipped
Tests, Linux 801 run, 730 passed, 41 failed, 30 skipped; every failure is filed (see Verification)

Contents

What changed since v0.1.0

  • The version is 0.2.0, in all three places it lives: current_version() in
    include/liquid/version.hpp, version_string() in src/version.cpp, and
    project(liquid VERSION ...) in CMakeLists.txt. liquid --version and liquid version print
    liquid 0.2.0. The library's VERSION/SOVERSION (the ABI version) do not move: there is no
    ABI change.
  • A test holds each place. Version.StringMatchesStruct already compared the string with the
    struct. The new Version.MatchesProjectVersion compares the code with project(VERSION), which
    the build passes in as LIQUID_PROJECT_VERSION, and the new ctest release-notes-page fails
    when docs/releases/v<project version>.md is missing.
  • Releases are cut from dev and promoted to main
    (#359, and this release's changes to
    CLAUDE.md Cutting a release and docs/releases/README.md). Feature branches
    and pull requests target dev; the release pull request (dev into main) is the only one that
    targets main, and its merge commit carries the tag.
  • Status lines in README.md, CLAUDE.md and docs/README.md name v0.2.0.

Where it has run

  • Lake v0.2.0 (release,
    2026-10-17) is built against liquid v0.1.0, commit f669726, which is liquid-bridge's pin of
    modules/liquid and the source every Lake image on the development clusters is compiled
    from. Its library source is identical to this release; only the version string differs. Lake's
    end-to-end suite on lake-testing drives the liquid binary (init, cut, push).
  • Lake v0.1.0 was built against liquid 88c5ef4, as the v0.1.0 page records.
  • liquify links libliquid from its own pin of liquid; this release does not move it.

What v0.2.0 does not include

Everything v0.1.0 does not include is still not
included. In short:

  • FUSE-backed commands: lazy mounts, wrap, verify and replay need libfuse3 on Linux and
    macFUSE on macOS, and liquid's own filesystem projection without FUSE is not written yet
    (#302,
    #303,
    #304).
  • Windows returns a documented unsupported result for the daemon, wrap, verify and
    replay.
  • The Phase 2 and Phase 4 exits are not demonstrated
    (#299,
    #300).
  • Long-lived hardware-backed keys (PIV, FIDO2, TPM sealing, threshold signing)
    (#81).
  • A memory-resident search index for liquid search: each query opens the on-disk index
    (#360).
  • The hosted service and the IDE are their own projects (Lake and liquify).
  • A licence. None has been chosen
    (liquid-bridge#2); the repository is
    private.

Known issues

Security-relevant first.

  • liquid-bridge#11 — no security
    review and no vulnerability disclosure policy yet. Both are required before liquid goes public.
  • liquid-bridge#1 — TAAP/1 subjects
    are key-derived, so nothing can be attested about a content-addressed object (a document, drip,
    change or artifact) until the object-subject form is specified.
  • #349 — creating the local identity
    races: concurrent first uses can leave it unreadable (cannot unwrap local identity).
  • #310 — the public constructors of
    forge_client and sync_endpoint throw across the library boundary.

Behaviour.

  • #361 — liquid deploy names the
    repository only by its liquid id. A Lake repository pushed from a clone of another shares that
    id, so Lake cannot tell which repository a deployment belongs to and does not show it
    (lake#805). Deployments of repositories with an
    unshared id are shown.
  • lake#776 — Lake's import_repository
    refuses an archive its export_repository just made (invalid sync item reference); the sync
    item format is liquid's.
  • #346 — SIGBUS inside liquid's runtime
    under heavy parallel test load.
  • #325 — block_on's runner threads use
    the platform default stack, which is 512 KiB on macOS.
  • #319 — the shared-library build fails
    to link the CLI on macOS, with undefined Boost symbols.
  • #341 — a one-file commit issues 57
    store barriers, which bounds a remote store by round trips.
  • #340 — the sync client does not retry
    a 503 that carries Retry-After.
  • Store ordering: #342 (no permanent root
    for objects no repository references), #343
    (a missing barrier after the last state removal of a repository operation) and
    #344 (the store_backend ordering contract
    between barriers is not stated).
  • #291 — the wrap, cache and provenance
    promises cannot be proven on the development Mac, because macFUSE is absent.
  • #281 — the real-world import gate is
    stale: main takes 1,773 s against a 900 s ceiling.

The suite.

  • Linux: 41 of 801 tests fail on the cluster BuildKit lane; counts and causes are under
    Verification.
    • #362 — tests that need a FUSE mount fail
      instead of skipping when /dev/fuse is absent (34), and
      BuildPlan.daemon_preserves_the_repository_plan_and_event_sequence crashes on the mount
      failure.
    • #363 — cli-offline and cli-log-url fail
      under the offline runner in a container.
    • #364 — cli-help-docs fails on CMake 3.x.
    • #365 — two HotUpdateDemo tests fail on
      Linux.
    • #356 —
      Projection.generated_values_cannot_change_shell_structure fails on Linux.
    • #348 — classifying the Linux failures and
      making the suite runnable in a container.
  • Intermittent tests: #354 and
    #336 (admission server),
    #353 (daemon under load),
    #264 (node store) and
    #225 (drip overflow on Linux).

Verification

macOS: full suite, run serially (ctest --test-dir build --output-on-failure, no -j) on the
release branch. macOS arm64, Homebrew Clang 22.1.8, Release, without macFUSE, 477 seconds:

747 tests · 735 passed · 0 failed · 12 skipped

The two tests beyond v0.1.0's 745 are Version.MatchesProjectVersion and release-notes-page.
The 12 skipped tests are the same 12 as v0.1.0, and each needs something this host lacks:
a FUSE mount (VfsMount.hydrates_captures_and_reuses_cache,
BuildWrap.mount_backed_scenarios_are_skipped_without_linux_fuse, vfs-conformance-libfuse), a
configured REAPI or NativeLink peer (Http2Interop ×2, RemoteInterop ×1), a node content store
(NodeStore ×2), native packaging peers (Projection.emit_* ×3), or a restart hook
(HotUpdateDemo.TierThreeInvokesRestartHook). So this run does not exercise wrap, verify,
replay or lazy mounts end to end (#291).

The build has no compiler warnings. ./build/liquid --version prints liquid 0.2.0. The CLI
reference generated from this binary (liquid docs --format json and --format markdown) is
identical to docs/reference/cli/.

Linux: the cluster BuildKit lane (codex-work/build/liquid-linux-test; Ubuntu 24.04, clang 19,
CMake 3.31.5, Release, kernel 6.8.0-1059-azure, running as root in an unprivileged container with
no /dev/fuse). The build has no errors. The suite does not pass on Linux, and this release
claims nothing about what failed.

Every target built, ctest -j 1, run twice with the same result:

801 tests · 730 passed · 41 failed · 30 skipped
Failed Cause Issue
34 A FUSE mount is needed and /dev/fuse is absent; the tests fail instead of skipping: 32 build executor and configuration gtests (BuildCache, BuildPlan, BuildEvents, BuildTests, Build, BuildVerification, BuildReplay, Configuration*), symbols-cli-build and vfs-conformance-libfuse. One is a crash: BuildPlan.daemon_preserves_the_repository_plan_and_event_sequence (SEGFAULT) #362
2 cli-offline (unshare not permitted) and cli-log-url (cannot link offline input: File exists) under the offline runner #363
1 cli-help-docs: tests/cli/help-docs.cmake uses IN_LIST without policy CMP0057, an error on CMake 3.x #364
2 HotUpdateDemo.TierOnePatchChangesARunningCapyLoop and TierThreeInvokesRestartHook; cause not yet known #365
1 Projection.generated_values_cannot_change_shell_structure (tests/test_projection.cpp:454), a Linux failure in every run regardless of load #356
1 Reported Not Run by ctest; the lane's log does not name it #348

The 30 skipped tests are skipped by their own guards: the 12 BuildWrap scenarios and
VfsMount.hydrates_captures_and_reuses_cache (FUSE), Http2Interop ×2, RemoteInterop ×1 and
BuildDistribution ×3 (REAPI or NativeLink peers), NodeStore ×2 (a node content store),
Projection.emit_* ×3 (packaging peers), TpmCustody (swtpm), DataBranch (local cluster
metadata), BuildPlan.cli_prints_configured_compile_and_link_actions,
BuildEvents.edit_during_build_replans_and_reports_untouched_hits,
BuildEvents.cli_prints_json_lines_and_preserves_failure_exit, and guides-run. None of these
is counted as proof.

The same tree with only liquid-tests built, ctest -j 4: 698 tests, 73 failed, 26 of them Not Run
(targets that build did not include). The single-process gtest run
(liquid-tests --gtest_filter='*') failed 33 tests, the gtests in the table above; in the first
of the three lane runs it failed 34, the extra one the intermittent
AdmissionServer.enforces_checkpoint_age_and_stricter_reload_over_http
(#336). The collapse of about 300 failures under
the parallel run that #356 recorded did not
reproduce.

Not done for this release: the shared-library build
(#319) and Windows.


Building it

git clone --recurse-submodules git@github.com:oramasearch/liquid.git
cd liquid
git checkout v0.2.0
cmake -S . -B build -G Ninja
cmake --build build
ctest --test-dir build

Prerequisites, options and the install layout are in
docs/build/local.md. Consuming the library from another CMake project is
in docs/library/libliquid.md.