fix(client): keep RDF 1.2 base direction (its:dir) in term writers and keys

termToNTriples and formatTerm wrote a directional literal such as
{"xml:lang":"en","its:dir":"ltr"} as "hi"@en, both at the top level and
inside a triple term, so site/GUI dataset snapshots changed the term's
identity and literals differing only by direction collapsed. Add its:dir
to SparqlAtomicTerm and emit it as @lang--dir. The site and GUI graph-view
node keys now include the direction too.

Tests: client writer/formatter (top-level, nested, parse round trip), site
rowsToNQuads round trip, GUI termToNT key round trip, and graph-view node
identity in both site and GUI.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ScyGGohDhirnbLbrUSnA5n

Author: claude

gui/app/src/lib/inferred-facts.test.ts

@@ -208,3 +208,24 @@ test("literal base direction is a key component on both paths", () => {
   const p: SparqlTerm = { type: "uri", value: "http://ex/p" };
   assert.equal(tripleKeyOfBindings(a, p, dirLit), ltr);
 });
+
+test("a directional literal inside a triple term round-trips through termToNT", () => {
+  const a: SparqlTerm = { type: "uri", value: "http://ex/a" };
+  const p: SparqlTerm = { type: "uri", value: "http://ex/p" };
+  const tt = (dir: string | undefined): SparqlTerm => ({
+    type: "triple",
+    value: {
+      subject: a,
+      predicate: p,
+      object: { type: "literal", value: "hi", "xml:lang": "en", "its:dir": dir },
+    },
+  });
+  for (const t of [tt("ltr"), tt("rtl"), tt(undefined)]) {
+    const line: string = `${termToNT(a)} ${termToNT(p)} ${termToNT(t)} .`;
+    assert.equal(keyOfLine(line), tripleKeyOfBindings(a, p, t));
+  }
+  // The snapshot keeps the direction, so terms differing only by it stay distinct.
+  assert.equal(termToNT(tt("ltr")), '<<( <http://ex/a> <http://ex/p> "hi"@en--ltr )>>');
+  assert.notEqual(termToNT(tt("ltr")), termToNT(tt("rtl")));
+  assert.notEqual(termToNT(tt("ltr")), termToNT(tt(undefined)));
+});

gui/app/src/lib/inferred-facts.ts

@@ -161,8 +161,7 @@ export function keyOfSparqlTerm(t: SparqlTerm): string {
     );
   }
   // SPARQL 1.2 results carry the base direction as a separate `its:dir` field.
-  const dir = (t as { "its:dir"?: string })["its:dir"];
-  return literalKey(t.value, t["xml:lang"], dir, t.datatype);
+  return literalKey(t.value, t["xml:lang"], t["its:dir"], t.datatype);
 }
 
 /** Canonical key of a whole triple from three SPARQL-JSON terms. */

gui/app/src/lib/select-result-graph.test.ts

@@ -40,3 +40,26 @@ test("declines literal-only aggregate-shaped SELECT results", () => {
   };
   assert.equal(deriveSelectResultGraph(results), null);
 });
+
+test("keeps literals that differ only by base direction as distinct nodes", () => {
+  const a = { type: "uri" as const, value: "http://example.com/a" };
+  const hi = (dir?: string) => ({
+    type: "literal" as const,
+    value: "hi",
+    "xml:lang": "en",
+    "its:dir": dir,
+  });
+  const results: SparqlResults = {
+    head: { vars: ["s", "v"] },
+    results: {
+      bindings: [
+        { s: a, v: hi("ltr") },
+        { s: a, v: hi("rtl") },
+        { s: a, v: hi() },
+      ],
+    },
+  };
+  const graph = deriveSelectResultGraph(results);
+  assert.ok(graph);
+  assert.equal(graph.nodes.length, 4);
+});

gui/app/src/lib/select-result-graph.ts

@@ -39,6 +39,8 @@ function termKey(term: SparqlTerm): string {
     term.value,
     term.type === "literal" ? (term.datatype ?? "") : "",
     term.type === "literal" ? (term["xml:lang"] ?? "") : "",
+    // RDF 1.2 base direction is part of the literal's identity.
+    term.type === "literal" ? (term["its:dir"] ?? "") : "",
   ]);
 }
 

packages/sparq-client/src/index.ts

@@ -101,12 +101,25 @@ export interface WasmModule {
 // SPARQL 1.1 JSON + SHACL report shapes (for rendering).
 // ---------------------------------------------------------------------------
 
-/** An IRI, blank node or literal in SPARQL-JSON form (`value` is the decoded lexical form). */
+/**
+ * An IRI, blank node or literal in SPARQL-JSON form (`value` is the decoded lexical form).
+ * A literal with an RDF 1.2 base direction carries the bare tag in `xml:lang` and the
+ * direction (`ltr` / `rtl`) in `its:dir`, as SPARQL 1.2 Query Results JSON does.
+ */
 export interface SparqlAtomicTerm {
   type: "uri" | "literal" | "bnode";
   value: string;
   datatype?: string;
   "xml:lang"?: string;
+  "its:dir"?: string;
+}
+
+/** A literal's language suffix with its base direction: `en`, or `en--ltr` for `its:dir`. */
+function langTag(t: SparqlAtomicTerm): string | undefined {
+  const lang = t["xml:lang"];
+  if (!lang) return undefined;
+  const dir = t["its:dir"];
+  return dir ? `${lang}--${dir}` : lang;
 }
 
 /**
@@ -120,6 +133,7 @@ export interface SparqlTripleTerm {
   value: { subject: SparqlTerm; predicate: SparqlTerm; object: SparqlTerm };
   datatype?: undefined;
   "xml:lang"?: undefined;
+  "its:dir"?: undefined;
 }
 
 /** One SPARQL-JSON term: an IRI / blank node / literal, or an RDF 1.2 triple term. */
@@ -155,7 +169,8 @@ function escapeNTriplesString(value: string): string {
  * triple term as `<<( s p o )>>`. The single shared term writer: every N-Triples/N-Quads
  * snapshot built from SPARQL-JSON bindings should route through this so a new term kind
  * cannot be silently dropped by one writer. A literal's lexical form is escaped the way the
- * engine's own serialiser does (backslash, double-quote, LF, CR); `xsd:string` is implicit.
+ * engine's own serialiser does (backslash, double-quote, LF, CR); `xsd:string` is implicit;
+ * an RDF 1.2 base direction (`its:dir`) is kept as `@lang--dir`.
  */
 export function termToNTriples(t: SparqlTerm): string {
   switch (t.type) {
@@ -169,7 +184,7 @@ export function termToNTriples(t: SparqlTerm): string {
     }
     case "literal": {
       const quoted = `"${escapeNTriplesString(t.value)}"`;
-      const lang = t["xml:lang"];
+      const lang = langTag(t);
       if (lang) return `${quoted}@${lang}`;
       if (t.datatype && t.datatype !== XSD_STRING_IRI) return `${quoted}^^<${t.datatype}>`;
       return quoted;
@@ -973,7 +988,8 @@ export function formatTerm(t: SparqlTerm | undefined): string {
     const { subject, predicate, object } = t.value;
     return `<<( ${formatTerm(subject)} ${formatTerm(predicate)} ${formatTerm(object)} )>>`;
   }
-  if (t["xml:lang"]) return `"${t.value}"@${t["xml:lang"]}`;
+  const lang = langTag(t);
+  if (lang) return `"${t.value}"@${lang}`;
   if (t.datatype && t.datatype !== "http://www.w3.org/2001/XMLSchema#string") {
     const short = t.datatype.replace("http://www.w3.org/2001/XMLSchema#", "xsd:");
     return `"${t.value}"^^${short}`;

packages/sparq-client/test/sparql-term.test.mjs

@@ -8,6 +8,7 @@ import { test } from "node:test";
 import {
   formatTerm,
   isTripleTerm,
+  parseNTriples,
   resultsToCsv,
   termToNTriples,
   termValue,
@@ -67,3 +68,52 @@ test("CSV export renders a triple term as its N-Triples form, not [object Object
   });
   assert.equal(csv, "t\r\n<<( <http://ex/alice> <http://ex/knows> <http://ex/alice> )>>");
 });
+
+// RDF 1.2 base direction: SPARQL 1.2 results carry it as a separate `its:dir` field next to
+// the bare `xml:lang` tag. `"hi"@en--ltr` and `"hi"@en` are different RDF terms, so every
+// writer must keep the direction, at the top level and inside a triple term.
+const hiLtr = { type: "literal", value: "hi", "xml:lang": "en", "its:dir": "ltr" };
+const hiRtl = { type: "literal", value: "hi", "xml:lang": "en", "its:dir": "rtl" };
+const hiPlain = { type: "literal", value: "hi", "xml:lang": "en" };
+
+test("termToNTriples keeps a top-level literal's base direction", () => {
+  assert.equal(termToNTriples(hiLtr), '"hi"@en--ltr');
+  assert.equal(termToNTriples(hiRtl), '"hi"@en--rtl');
+  assert.equal(termToNTriples(hiPlain), '"hi"@en');
+});
+
+test("termToNTriples keeps base direction inside a (nested) triple term", () => {
+  const tt = (o) => ({ type: "triple", value: { subject: alice, predicate: knows, object: o } });
+  assert.equal(
+    termToNTriples(tt(hiLtr)),
+    '<<( <http://ex/alice> <http://ex/knows> "hi"@en--ltr )>>',
+  );
+  assert.equal(
+    termToNTriples(tt(tt(hiRtl))),
+    '<<( <http://ex/alice> <http://ex/knows> <<( <http://ex/alice> <http://ex/knows> "hi"@en--rtl )>> )>>',
+  );
+  // Terms differing only by direction must not collapse.
+  const forms = new Set([hiLtr, hiRtl, hiPlain].map((o) => termToNTriples(tt(o))));
+  assert.equal(forms.size, 3);
+});
+
+test("formatTerm keeps base direction, top-level and nested", () => {
+  assert.equal(formatTerm(hiLtr), '"hi"@en--ltr');
+  assert.equal(formatTerm(hiPlain), '"hi"@en');
+  assert.equal(
+    formatTerm({ type: "triple", value: { subject: alice, predicate: knows, object: hiRtl } }),
+    '<<( <http://ex/alice> <http://ex/knows> "hi"@en--rtl )>>',
+  );
+});
+
+test("a directional literal nested in a triple term survives a snapshot round trip", () => {
+  const o = { type: "triple", value: { subject: alice, predicate: knows, object: hiLtr } };
+  const line = `${termToNTriples(alice)} ${termToNTriples(knows)} ${termToNTriples(o)} .`;
+  const { statements } = parseNTriples(line);
+  assert.equal(statements.length, 1);
+  const back = statements[0].o;
+  assert.equal(back.kind, "triple");
+  assert.equal(back.o.kind, "literal");
+  assert.equal(back.o.value, "hi");
+  assert.equal(back.o.lang, "en--ltr");
+});

site/src/lib/result-graph-shape.ts

@@ -21,14 +21,16 @@ import type { SparqlResults, SparqlTerm } from "./sparq-wasm";
 export const MAX_GRAPH_NODES = 24;
 
 /**
- * A stable, INJECTIVE identity key for a term: same lexical value but different datatype/lang ⇒
+ * A stable, INJECTIVE identity key for a term: same lexical value but different datatype/lang/dir ⇒
  * different node. Shared with deriveGraph (result-graph.ts) so the predicate's admission order and
  * the derivation's node identity can never disagree.
  */
 export function termKey(t: SparqlTerm): string {
   const dt = t.type === "literal" ? (t.datatype ?? "") : "";
   const lang = t.type === "literal" ? (t["xml:lang"] ?? "") : "";
-  return JSON.stringify([t.type, t.value, dt, lang]);
+  // RDF 1.2 base direction is part of the literal's identity (`"hi"@en--ltr` ≠ `"hi"@en`).
+  const dir = t.type === "literal" ? (t["its:dir"] ?? "") : "";
+  return JSON.stringify([t.type, t.value, dt, lang, dir]);
 }
 
 /**

site/test/repl-dataset.test.mjs

@@ -20,6 +20,7 @@ import {
   DEFAULT_GRAPH_COUNT_QUERY,
   parseGraphStats,
 } from "../src/lib/repl-dataset.ts";
+import { parseNTriples } from "@sparq/client";
 
 test("isDatasetFormat is true exactly for the quad-bearing formats", () => {
   // Quad formats carry named graphs and must be loaded with loadDataset.
@@ -112,6 +113,32 @@ test("rowsToNQuads writes an RDF 1.2 triple term as <<( s p o )>>", () => {
   assert.ok(!out.includes("undefined"));
 });
 
+// RDF 1.2 base direction (`its:dir` in SPARQL 1.2 JSON) is part of a literal's identity:
+// a snapshot must write `"hi"@en--ltr`, at the top level and inside a triple term.
+test("rowsToNQuads round-trips a directional literal, top-level and in a triple term", () => {
+  const a = { type: "uri", value: "http://ex/a" };
+  const p = { type: "uri", value: "http://ex/p" };
+  const hi = (dir) => ({ type: "literal", value: "hi", "xml:lang": "en", "its:dir": dir });
+  const tt = (o) => ({ type: "triple", value: { subject: a, predicate: p, object: o } });
+  const rows = [
+    { s: a, p, o: hi("ltr") },
+    { s: a, p, o: tt(hi("rtl")) },
+    { s: a, p, o: tt(hi(undefined)) },
+  ];
+  const nq = rowsToNQuads(rows);
+  assert.equal(
+    nq,
+    '<http://ex/a> <http://ex/p> "hi"@en--ltr .\n' +
+      '<http://ex/a> <http://ex/p> <<( <http://ex/a> <http://ex/p> "hi"@en--rtl )>> .\n' +
+      '<http://ex/a> <http://ex/p> <<( <http://ex/a> <http://ex/p> "hi"@en )>> .',
+  );
+  const { statements } = parseNTriples(nq);
+  assert.deepEqual(
+    statements.map((st) => (st.o.kind === "triple" ? st.o.o.lang : st.o.lang)),
+    ["en--ltr", "en--rtl", "en"],
+  );
+});
+
 test("rowsToNQuads emits a quad line (with the graph) for named-graph rows", () => {
   const rows = [
     {

site/test/result-graph.test.mjs

@@ -178,6 +178,24 @@ test("deriveGraph: literals with the same value but different datatype are disti
   assert.equal(g.nodes.length, 3);
 });
 
+test("deriveGraph: literals differing only by base direction are distinct nodes", () => {
+  const a = { type: "uri", value: "http://ex/a" };
+  const hi = (dir) => ({ type: "literal", value: "hi", "xml:lang": "en", "its:dir": dir });
+  const g = deriveGraph({
+    head: { vars: ["s", "v"] },
+    results: {
+      bindings: [
+        { s: a, v: hi("ltr") },
+        { s: a, v: hi("rtl") },
+        { s: a, v: hi(undefined) },
+      ],
+    },
+  });
+  assert.ok(g);
+  // http://ex/a + "hi"@en--ltr + "hi"@en--rtl + "hi"@en = 4 distinct nodes.
+  assert.equal(g.nodes.length, 4);
+});
+
 test("deriveGraph: delimiter-containing lexical/datatype fields keep terms distinct (no key collision)", () => {
   // Regression: the term identity key must be INJECTIVE. It once concatenated (value, datatype,
   // lang) with a single-character delimiter, so a delimiter INSIDE one field could forge another