V0.3.1/woql dsl v0 2

[thanos]

---

Overview

v0.3.1 brings the WOQL DSL from a 7-operator v0.1 subset to a fully usable
~70-operator surface (Tier 1+2), matching the Python/JS clients' vocabulary.
This release introduces a wire-correct 4-wrapper value model, a dual-mode path
DSL (string-compiled parser + structured builders), and full round-trip
serialization for every operator.

The encoder was refactored to match the canonical WOQL JSON-LD wire format,
fixing two latent bugs in the v0.3 encoder (read_document field ordering and
triple object encoding).

What's new

WOQL DSL v0.2 (ADR-0008)

Expanded from 7 to ~70 operators across all major families:

• Logical combinators (4): not_/1, opt/1 (alias optional/1),
  once/1, immediately/1.
• Query modifiers (9): distinct/2, limit/2, start/2, order_by/2
  (accepts tuple-list [{"v:Name", :asc}] or keyword-list [name: :asc]),
  group_by/4, count/2, collect/3, star/0, all/0.
• Graph patterns (12): quad/4, added_triple/3, removed_triple/3,
  added_quad/4, removed_quad/4, add_triple/3, delete_triple/3,
  add_quad/4, delete_quad/4, update_triple/3, update_quad/4.
• Comparison (5): less/2, greater/2, gte/2, lte/2, like/3.
• Schema ops (3): isa/2, sub/2 (alias subsumption/2), cast/3
  (alias typecast/3).
• Arithmetic (9): eval/2, plus/1, minus/1, times/1, divide/1,
  div/1, exp/2, floor/1, sum/2.
• String ops (10): concat/2, join/3, substr/5, trim/2, upper/2,
  lower/2, pad/4, split/3, length/2, regexp/3.
• List/Set/Dict (8): dot/3, member/2, slice/4, set_difference/3,
  set_intersection/3, set_union/3, set_member/2, list_to_set/2.
• Path/navigation (1): path/3..4 with dual-mode DSL.
• ID generation (3): unique/3, idgen/3, idgen_random/2.
• Documents (3): insert_document/1, update_document/1,
  delete_document/1.
• Graph context (4): using/2, from/2, into/2, comment/2.
• Graph meta (2): size/2, triple_count/2.
• Literal/value helpers (8): var/1, iri/1, string/1, boolean/1,
  datetime/1, date/1, literal/2, true_/0.

Dual-mode Path DSL

Path queries accept both string patterns and structured builders:

# String pattern — compiled via tokenizer
WOQL.path("v:S", "friend*{1,3}", "v:O")

# Structured — idiomatic Elixir, no parser
WOQL.path("v:S",
  WOQL.Path.path_star(WOQL.Path.path_pred("friend")),
  "v:O"
)

String pattern grammar: predicates (friend), inverse (<friend), star
(*), plus (+), bounded repetition ({n}, {n,m}, {n,}), alternation
(|), sequencing (,), any (.), and grouping ((...)).

4-wrapper value model

The JSON-LD encoder now uses four value-wrapper types matching the Python/JS
clients:

Wrapper	Used for
NodeValue	Subjects, predicates, identifiers, IRIs
Value	Triple objects, comparison operands, type_of, read_document
DataValue	String-op operands, ID-gen keys
ArithmeticValue	Arithmetic operands

Module split

woql.ex split into sub-modules following the Client.Params pattern:

lib/terminus_db/woql.ex           # public API, execute, to_jsonld/from_jsonld
lib/terminus_db/woql/encoder.ex   # 4-wrapper JSON-LD encoder
lib/terminus_db/woql/decoder.ex   # JSON-LD → Query struct
lib/terminus_db/woql/path.ex      # path pattern parser + structured builders
lib/terminus_db/woql/literal.ex   # value/literal helpers

Tests

• 442 unit tests + 119 doctests + 9 properties, 0 failures.
• 27 integration tests (against live TerminusDB 12, excluded from default run).
• 94.0% coverage (enforced minimum 80%).
• Property tests: random query trees round-trip through to_jsonld ∘ from_jsonld.
• Every operator has builder, encoder, decoder, and round-trip tests.

Breaking changes

1. triple/3 object encoding: constant string objects now encode as
   Value with xsd:string data (literals), matching Python. Previously they
   encoded as NodeValue with node (IRIs). Migration: pass
   WOQL.iri("...") explicitly when an IRI object is intended.

2. read_document/2 field ordering: the document id is now under
   "identifier" (NodeValue) and the output variable under "document"
   (Value), matching the canonical wire format. Previously these were swapped.

3. eq/2 operands: now wrapped in Value (was DataValue).

4. type_of/2: both value and type now use Value (was
   NodeValue for type).

Bug fixes

• read_document/2: field ordering now matches the canonical WOQL JSON-LD
  wire format (was reversed, causing incorrect encoding).