thanos · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -109,47 +109,46 @@ jobs:
       - name: Build docs
         run: mix docs
 
-  # integration:
-  #   name: Integration tests (real TerminusDB)
-  #   runs-on: ubuntu-latest
-  #   env:
-  #     MIX_ENV: test
-  #     TERMINUSDB_URL: "http://localhost:6363"
-  #     TERMINUSDB_USER: "admin"
-  #     TERMINUSDB_KEY: "root"
-  #   services:
-  #     terminusdb:
-  #       image: terminusdb/terminusdb-server:latest
-  #       ports:
-  #         - 6363:6363
-  #       env:
-  #         TERMINUSDB_ADMIN_PASS: root
-  #   steps:
-  #     - uses: actions/checkout@v4
-
-  #     - name: Set up Elixir
-  #       uses: erlef/setup-beam@v1
-  #       with:
-  #         elixir-version: "1.20.1"
-  #         otp-version: "28"
-
-  #     - name: Install dependencies
-  #       run: mix deps.get
-
-  #     - name: Wait for TerminusDB to be ready
-  #       run: |
-  #         echo "Waiting for TerminusDB at http://localhost:6363..."
-  #         for i in $(seq 1 30); do
-  #           if curl -sf http://localhost:6363/api/ok >/dev/null 2>&1; then
-  #             echo "TerminusDB is ready (attempt $i)."
-  #             exit 0
-  #           fi
-  #           echo "  attempt $i/30 - not ready yet, retrying in 2s..."
-  #           sleep 2
-  #         done
-  #         echo "::error::TerminusDB did not become ready within 60s."
-  #         docker logs "$(docker ps -q --filter ancestor=terminusdb/terminusdb-server:latest)" 2>&1 | tail -30
-  #         exit 1
-
-  #     - name: Run integration tests
-  #       run: mix test --only integration
+  integration:
+    name: Integration tests (real TerminusDB)
+    runs-on: ubuntu-latest
+    env:
+      MIX_ENV: test
+      TERMINUSDB_URL: "http://localhost:6363"
+      TERMINUSDB_USER: "admin"
+      TERMINUSDB_KEY: "root"
+    services:
+      terminusdb:
+        image: terminusdb/terminusdb-server:v12-noroot
+        ports:
+          - 6363:6363
+        env:
+          TERMINUSDB_ADMIN_PASS: root
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Elixir
+        uses: erlef/setup-beam@v1
+        with:
+          elixir-version: "1.20.1"
+          otp-version: "28"
+
+      - name: Install dependencies
+        run: mix deps.get
+
+      - name: Wait for TerminusDB to be ready
+        run: |
+          echo "Waiting for TerminusDB at http://localhost:6363..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:6363/api/ok >/dev/null 2>&1; then
+              echo "TerminusDB is ready (attempt $i)."
+              exit 0
+            fi
+            echo "  attempt $i/30 - not ready yet, retrying in 2s..."
+            sleep 2
+          done
+          echo "::error::TerminusDB did not become ready within 60s."
+          docker logs "$(docker ps -q --filter ancestor=terminusdb/terminusdb-server:latest)" 2>&1 | tail -30
+          exit 1
+
+      - name: Run integration tests
+        run: mix test --only integration
diff --git a/AGENTS.md b/AGENTS.md
@@ -100,7 +100,7 @@ If you cannot find a command, ask the user and then add it here.
 
 ## Dependency policy
 
-Minimize deps. Runtime (v0.2): `req`, `jason`, `nimble_options`, `telemetry`.
+Minimize deps. Runtime (v0.3): `req`, `jason`, `nimble_options`, `telemetry`.
 Ecto and ExDatalog will be **optional** dependencies, gated by compile flags,
 when their integrations land (v0.3/v0.4). Do not add a runtime dep without an
 ADR justifying it.
@@ -111,9 +111,10 @@ ADR justifying it.
 | --- | --- | --- |
 | **v0.1 (foundation)** | Config, Error, Telemetry, Client (Req), Database API, unit tests, CI, ADRs, ARCHITECTURE, AGENTS | **Done** |
 | **v0.2 (APIs)** | Document, Schema, Branch, Streaming, Document.query/stream, guides, Livebook | **Done** |
-| v0.2.1+ | Commit, Diff, Merge, GraphQL, WOQL functional DSL, benchmarks | Pending |
-| v0.3 (Ecto) | `use TerminusDB.Schema` macro, schema generation, optional `:ecto` dep; research full `Ecto.Adapter` feasibility | Pending |
-| v0.4 (ExDatalog) | `TerminusDB.Datalog` bridge (`to_woql`, `to_jsonld`, `from_triples`), optional `:datalog` dep | Pending |
+| **v0.3 (versioned workflows)** | Commit, Diff, Merge (rebase), WOQL DSL v0.1, TerminusDB 12 compat, integration tests | **Done** |
+| v0.3.1+ | GraphQL, WOQL DSL v0.2 (more vocabulary), benchmarks, tutorials | Pending |
+| v0.4 (Ecto) | `use TerminusDB.Schema` macro, schema generation, optional `:ecto` dep; research full `Ecto.Adapter` feasibility | Pending |
+| v0.5 (ExDatalog) | `TerminusDB.Datalog` bridge (`to_woql`, `to_jsonld`, `from_triples`), optional `:datalog` dep | Pending |
 | Release | CHANGELOG, release notes, migration guide, Hex.pm review, final review | Pending |
 
 ## Key references

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -140,9 +140,11 @@ the graph engine.
   telemetry, and the HTTP/wire primitives.
 - **v0.2 (done):** Document CRUD + query + streaming, Schema frame retrieval,
   Branch management, and the concatenated-JSON streaming decoder.
-- **v0.2.1+:** Commit, Diff, Merge, GraphQL, and the WOQL functional DSL.
-- **v0.3:** Ecto integration (`TerminusDB.Schema`) - Option B.
-- **v0.4:** ExDatalog integration - Option C.
+- **v0.3 (done):** Commit history, Diff, Merge (rebase), WOQL functional DSL
+  v0.1, TerminusDB 12 compatibility, and integration tests.
+- **v0.3.1+:** GraphQL, expanded WOQL vocabulary, benchmarks, tutorials.
+- **v0.4:** Ecto integration (`TerminusDB.Schema`) - Option B.
+- **v0.5:** ExDatalog integration - Option C.
 - **Option D is rejected** for v0.x; a local engine is out of scope for a client.
 
 This sequencing gives a usable, tested client immediately and de-risks the harder
@@ -164,12 +166,12 @@ TerminusDB
 ├── Schema                schema frame API                    ✓ v0.2
 ├── Branch                branch API                          ✓ v0.2
 ├── Streaming             concatenated-JSON stream decoder    ✓ v0.2
-├── Commit                history / log                       (v0.2.1+)
-├── Diff                  diff + patch                        (v0.2.1+)
-├── Merge                 push / pull / rebase                (v0.2.1+)
-├── WOQL                  functional DSL → JSON-LD            (v0.2.1+)
-├── GraphQL               GraphQL execution                   (v0.2.1+)
-├── Datalog               ExDatalog integration               (v0.4)
+├── Commit                history / log                       ✓ v0.3
+├── Diff                  diff / compare                      ✓ v0.3
+├── Merge                 rebase / merge                       ✓ v0.3
+├── WOQL                  functional DSL → JSON-LD            ✓ v0.3
+├── GraphQL               GraphQL execution                   (v0.3.1+)
+├── Datalog               ExDatalog integration               (v0.5)
 └── Telemetry             event definitions + helpers
 ```
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,54 @@ All notable changes to `terminusdb_ex` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] — 2026-06-25
+
+### Added — versioned query workflows and WOQL DSL
+
+- **`TerminusDB.Commit`**: commit history and inspection — `log/2`, `history/2`,
+  `get/3` (plus `!/` variants). Branch-aware with pagination (`:start`, `:limit`).
+- **`TerminusDB.Diff`**: document and branch-level diff — `compare/2` /
+  `compare!/2`. Supports `before`/`after` document values or branch/commit refs,
+  plus `:keep` for field preservation.
+- **`TerminusDB.Merge`**: branch merge (rebase) — `merge/2` (plus
+  `!/` variant). Uses the `/api/rebase` endpoint with `author`/`rebase_from`
+  body.
+- **`TerminusDB.WOQL`**: functional builder DSL (ADR-0002) — `triple/3`,
+  `and_/1`, `or_/1`, `eq/2`, `select/2`, `read_document/2`, `type_of/2`.
+  Serializes to the correct WOQL JSON-LD wire format (`NodeValue`/`DataValue`
+  wrappers, short type names like `"Triple"`, `"Equals"`). `to_jsonld/1` and
+  `from_jsonld/1` are round-trip tested. `execute/3` / `execute!/3` POST to
+  `/api/woql/:org/:db/:repo/branch/:branch` with `commit_info` support.
+- Telemetry areas `:commit` and `:woql` added to `TerminusDB.Telemetry`.
+- Integration tests for commit log/history, diff, merge (branch divergence +
+  rebase), and WOQL execution against a live TerminusDB 12.
+- Overview guide updated with Commit, Diff, Merge, and WOQL DSL sections.
+- 58 new unit tests (Commit, Diff, Merge, WOQL including round-trips).
+
+### Fixed (discovered via integration testing against TerminusDB 12)
+
+- `Schema.frame/3`: class name is now a `?type=` query param, not a path
+  segment (server returns 404 for path-appended class names).
+- `Branch.exists?/3`: rewrote to check `db/:org/:db?branches=true` branch list
+  (the `/branch` endpoint only supports POST/DELETE, not HEAD or GET).
+- `Document.query/3`: now always sends `as_list=true` (server returns
+  concatenated JSON by default, which crashes Req's JSON decoder).
+- `Commit.history/2`: uses the `/log` endpoint (the `/history` endpoint requires
+  a commit ID and cannot list without one).
+- `WOQL.eq/2`: type is `"Equals"` not `"Eq"`; literals are wrapped in
+  `DataValue` with xsd type annotations.
+- `Merge.merge/2`: uses `/rebase` with `author`/`rebase_from` body (not
+  `/pull` with `remote`/`remote_branch`, which causes 500 on local merges).
+- `WOQL.execute/3`: now includes `:repo`/`:branch` in the WOQL path
+  (`woql/:org/:db/:repo/branch/:branch`).
+
+### Changed
+
+- Version bumped to 0.3.0; `source_ref` updated for HexDocs.
+- TerminusDB 12 compatibility verified (v12.0.5): range queries, ISO8601 date
+  predicates, WOQL `comment`/`collect` predicates, cardinality on `Set`,
+  `@metadata`/`@context` JSON handling, diff+streaming in history endpoint.
+
 ## [0.2.0] — 2026-06-24
 
 ### Added — document, schema, branch, and streaming APIs
@@ -110,3 +158,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 [0.1.0]: https://github.com/thanos/terminusdb-client-elixir/releases/tag/v0.1.0
 [0.2.0]: https://github.com/thanos/terminusdb-client-elixir/releases/tag/v0.2.0
+[0.3.0]: https://github.com/thanos/terminusdb-client-elixir/releases/tag/v0.3.0
diff --git a/README.md b/README.md
@@ -11,11 +11,11 @@ graph database with built-in version control. It is built on
 [Req](https://hexdocs.pm/req) and treats connection context as **immutable data**,
 making it safe for concurrent use.
 
-> **Status:** v0.2.0. `Config`, `Error`, `Telemetry`, `Client`, `Database`,
-> `Document` (with streaming), `Schema`, and `Branch` are implemented and tested.
-> Commit, diff, merge, WOQL DSL, GraphQL, and optional Ecto/ExDatalog integrations
-> are planned for later milestones. See `ARCHITECTURE.md` and `AGENTS.md` for the
-> roadmap.
+> **Status:** v0.3.0. `Config`, `Error`, `Telemetry`, `Client`, `Database`,
+> `Document` (with streaming), `Schema`, `Branch`, `Commit`, `Diff`, `Merge`,
+> and `WOQL` are implemented and tested. GraphQL, Ecto, and ExDatalog
+> integrations are planned for later milestones. See `ARCHITECTURE.md` and
+> `AGENTS.md` for the roadmap.
 
 ## Installation
 
@@ -24,7 +24,7 @@ Add `terminusdb_client` to your dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:terminusdb_client, "~> 0.2.0"}
+    {:terminusdb_client, "~> 0.3.0"}
   ]
 end
 ```

diff --git a/docker-compose.yml b/docker-compose.yml
@@ -1,8 +1,6 @@
-version: "3.8"
-
 services:
   terminusdb:
-    image: terminusdb/terminusdb-server:latest
+    image: terminusdb/terminusdb-server:v12-noroot
     ports:
       - "6363:6363"
     environment: