V0.3.0/vc woql

[thanos]

Overview

v0.3.0 transforms the client from a document CRUD library into a
TerminusDB-native client exposing versioned data workflows. This release adds
commit history, diff, merge (rebase), and a WOQL functional query DSL, all
validated against a live TerminusDB 12.0.5 server.

Eight real bugs in the v0.2 code were discovered via integration testing and
fixed in this release.

What's new

TerminusDB.Commit

Commit history and inspection over the /api/log and /api/history endpoints:

• log/2 / log!/2 — concise log of recent commits on a branch, with
  pagination (:start, :limit).
• history/2 / history!/2 — full commit chain with metadata.
• get/3 / get!/3 — retrieve a single commit by descriptor ID.

All functions are branch-aware (:branch override) and support
:organization/:repo overrides.

TerminusDB.Diff

Document and branch-level diff over the /api/diff endpoint:

• compare/2 / compare!/2 — diff two document values or branch/commit refs.
  Supports before/after (document maps or resource refs) and :keep for
  field preservation.

TerminusDB.Merge

Branch merge (rebase) over the /api/rebase endpoint:

• merge/2 / merge!/2 — rebase a source branch onto a target branch, with
  :author/:message commit metadata.

TerminusDB.WOQL

Functional builder DSL for WOQL (ADR-0002), serializing to the correct JSON-LD
wire format:

• Builders: triple/3, and_/1, or_/1, eq/2, select/2,
  read_document/2, type_of/2.
• to_jsonld/1 — serialize to the WOQL JSON-LD format with NodeValue/
  DataValue wrappers and short type names ("Triple", "Equals", etc.).
• from_jsonld/1 — deserialize back to a WOQL.Query struct. Round-trip
  tested for all supported operations.
• execute/3 / execute!/3 — POST to /api/woql/:org/:db/:repo/branch/:branch
  with commit_info support for write queries.

Telemetry

Added :commit and :woql to the telemetry area type. All new modules emit
[:terminusdb, <area>, :start|:stop] events.

Documentation

• Overview guide updated with four new sections: Commit history (section 9),
  Diff (section 10), Merge (section 11), WOQL DSL (section 12).

Tests

• 217 unit tests + 6 properties + 38 doctests, 0 failures.
• 14 integration tests, 0 failures (against live TerminusDB 12.0.5).
• 94.0% coverage (enforced minimum 80% via coveralls.json).

Bug fixes (discovered via integration testing)

1. Schema.frame/3: class name is now a ?type= query param, not a path
   segment (server returns 404 for path-appended class names).
2. Branch.exists?/3: rewrote to check db/:org/:db?branches=true branch list
   (the /branch endpoint only supports POST/DELETE, not HEAD or GET).
3. Document.query/3: now always sends as_list=true (server returns
   concatenated JSON by default, which crashes Req's JSON decoder).
4. Commit.history/2: uses the /log endpoint (the /history endpoint
   requires a commit ID and cannot list without one).
5. WOQL.eq/2: type is "Equals" not "Eq"; literals are wrapped in
   DataValue with xsd type annotations.
6. Merge.merge/2: uses /rebase with author/rebase_from body (not
   /pull with remote/remote_branch, which causes 500 on local merges).
7. WOQL.execute/3: now includes :repo/:branch in the WOQL path.
8. Database integration tests: fixed to match actual v12 response shapes
   (path field, map not list).

TerminusDB 12 compatibility

Verified against TerminusDB 12.0.5. Key v12 features documented:

• Range queries over triples (v12.0.4)
• ISO8601 date/time/interval predicates, Allen interval algebra (v12.0.4)
• WOQL comment and collect predicates (v12.0.4)
• Cardinality constraints on Set (v12.0.4)
• @metadata and @context JSON handling in schema (v12.0.4)
• Diff and streaming in the history endpoint (v12.0.5)
• merge_repeats on document interface update (v12.0.5)

The WOQL DSL is designed for easy extension to these new predicates in future
releases.

Breaking changes

• Schema.frame/3: no longer appends the class name to the URL path; instead
  sends it as a ?type= query parameter. This is the correct TerminusDB API
  usage but changes the outgoing request.
• Branch.exists?/3: now queries db/:org/:db?branches=true instead of
  HEAD/GET on the branch resource. Returns true/false the same way.
• Merge.merge/2: uses /rebase instead of /pull. The body format changed
  from remote/remote_branch to author/rebase_from.
• WOQL JSON-LD format: uses short type names ("Triple", "Equals") and
  NodeValue/DataValue wrappers, not woql: prefixed types.
• Commit.history/2: uses the /log endpoint instead of /history.

Dependencies

Runtime (unchanged): req ~> 0.5, jason ~> 1.4, nimble_options ~> 1.1,
telemetry ~> 1.2.