From 7d2617811e189ae63cec7e395e3d163b6babaa6a Mon Sep 17 00:00:00 2001 From: Mahesh VAIKRI Date: Thu, 5 Nov 2026 16:17:10 -0600 Subject: [PATCH 01/11] Start the Core conformance corpus with its Python runner One golden fixture and prose were all that said the six ports agree on what a document means. vectors/manifest.ison now indexes executable documents, each with a per-port expectation, and ison-graph/tests/ test_vectors.py runs them as part of the Python suite. A meta-test pins the rules the runners assume: LF-only files ending in one newline, unique ids, existing files, and that a port says 'todo' exactly when it has no runner, so a port cannot be half-admitted. Two vectors to start; the rest follow by group. Co-Authored-By: Claude Fable 5.1 --- .gitattributes | 3 + ison-graph/tests/test_vectors.py | 144 +++++++++++++++++++++++++++++++ vectors/README.md | 10 +++ vectors/ids/positive-int.ison | 8 ++ vectors/ids/twin-int-string.ison | 4 + vectors/manifest.ison | 8 ++ 6 files changed, 177 insertions(+) create mode 100644 ison-graph/tests/test_vectors.py create mode 100644 vectors/README.md create mode 100644 vectors/ids/positive-int.ison create mode 100644 vectors/ids/twin-int-string.ison create mode 100644 vectors/manifest.ison diff --git a/.gitattributes b/.gitattributes index fe48232..89f0ae9 100644 --- a/.gitattributes +++ b/.gitattributes @@ -11,3 +11,6 @@ *.jpg binary *.gif binary *.ico binary + +# Conformance vectors are compared byte-for-byte by every port's test suite +vectors/** text eol=lf diff --git a/ison-graph/tests/test_vectors.py b/ison-graph/tests/test_vectors.py new file mode 100644 index 0000000..79d856e --- /dev/null +++ b/ison-graph/tests/test_vectors.py @@ -0,0 +1,144 @@ +"""Core Conformance Corpus runner - Python is the reference port. + +Reads vectors/manifest.ison with ison-py, loads every vector document and +checks this port's expectation column. The grammar of that column and the +meaning of every other column are in vectors/README.md. +""" + +from __future__ import annotations + +import re +from pathlib import Path + +import pytest +from ison_parser import loads + +from ison_graph import ISONGraph + +ROOT = Path(__file__).resolve().parents[2] +VECTORS = ROOT / "vectors" +PORT = "python" + +#: Runner file per port, relative to the repo root. A port column may say +#: 'todo' only while its runner does not exist - admission is atomic. +RUNNERS = { + "python": "ison-graph/tests/test_vectors.py", + "ts": "ison-graph-ts/src/vectors.test.ts", + "js": "ison-graph-js/src/vectors.test.js", + "rust": "ison-graph-rs/tests/vectors.rs", + "cs": "ison-graph-cs/tests/IsonGraph.Tests/VectorsTests.cs", + "cpp": "ison-graph-cpp/tests/test_vectors.cpp", +} +PORTS = tuple(RUNNERS) +EXPECTATIONS = ("pass", "pass:canonicalized", "pass:lossy", "defect", "todo") + + +def _read(rel: str) -> str: + # newline='' keeps '\n' exactly; read_text would translate on Windows. + with open(VECTORS / rel, encoding="utf-8", newline="") as f: + return f.read() + + +def _manifest() -> list[dict]: + doc = loads(_read("manifest.ison")) + rows = [r for b in doc.blocks if b.kind == "table" and b.name == "vectors" for r in b.rows] + assert rows, "manifest.ison has no table.vectors rows" + return rows + + +ROWS = _manifest() + + +def _load(rel: str, text: str) -> ISONGraph: + return ISONGraph.from_isonl(text) if rel.endswith(".isonl") else ISONGraph.from_ison(text) + + +def _emit(graph: ISONGraph) -> str: + return graph.to_ison() + "\n" + + +def _findings_ids() -> set[str]: + text = _read("README.md") + return set(re.findall(r"^\| (\S+) \|", text, flags=re.M)) - {"vector", "---"} + + +# ============================================================================= +# Meta-test: the manifest and files are what the runners assume they are. +# ============================================================================= + +def test_manifest_integrity(): + ids = [r["id"] for r in ROWS] + assert len(ids) == len(set(ids)), "duplicate vector ids" + + findings = _findings_ids() + for row in ROWS: + assert row["semantic"] in ("identifiable", "out_of_domain"), row["id"] + assert (row["semantic"] == "identifiable") == (row["reason"] is None), row["id"] + assert row["digest"] is None, row["id"] + assert isinstance(row["directed"], bool), row["id"] + assert isinstance(row["nodes"], int) and isinstance(row["edges"], int), row["id"] + + for key in ("file", "canonical"): + rel = row[key] + if rel is None: + continue + path = VECTORS / rel + assert path.is_file(), f"{row['id']}: {key} {rel} missing" + data = path.read_bytes() + assert b"\r" not in data, f"{rel}: CRLF" + assert not data.startswith(b"\xef\xbb\xbf"), f"{rel}: BOM" + assert data.endswith(b"\n") and not data.endswith(b"\n\n"), f"{rel}: must end in exactly one LF" + data.decode("utf-8") # raises on invalid UTF-8 + + cells = {p: row[p] for p in PORTS} + for port, cell in cells.items(): + assert isinstance(cell, str) and cell, f"{row['id']}: {port} empty" + assert cell in EXPECTATIONS or cell.startswith("reject:"), f"{row['id']}: {port}={cell!r}" + runner_exists = (ROOT / RUNNERS[port]).is_file() + assert (cell == "todo") == (not runner_exists), ( + f"{row['id']}: {port} is {cell!r} but runner " + f"{'exists' if runner_exists else 'is missing'}" + ) + if cell == "defect": + assert row["id"] in findings, f"{row['id']}: {port}=defect needs a README Findings row" + + wants_canonical = any(c == "pass:canonicalized" for c in cells.values()) + assert (row["canonical"] is not None) == wants_canonical, ( + f"{row['id']}: canonical must be set iff some port is pass:canonicalized" + ) + + +# ============================================================================= +# Runner +# ============================================================================= + +@pytest.mark.parametrize("row", ROWS, ids=[r["id"] for r in ROWS]) +def test_vector(row): + expectation = row[PORT] + text = _read(row["file"]) + + if expectation.startswith("reject:"): + with pytest.raises(Exception) as info: + _load(row["file"], text) + assert type(info.value).__name__ == expectation[len("reject:"):] + return + + graph = _load(row["file"], text) + assert graph.directed == row["directed"] + assert graph.node_count() == row["nodes"] + assert graph.edge_count() == row["edges"] + + out = _emit(graph) + if expectation == "defect": + # Contradicts the spec (see README Findings) - but pin what the port + # does so a wrong reading cannot drift into a different wrong one. + assert _emit(ISONGraph.from_ison(out)) == out + elif expectation == "pass": + assert out == text + elif expectation == "pass:canonicalized": + assert out == _read(row["canonical"]) + assert _emit(ISONGraph.from_ison(out)) == out + elif expectation == "pass:lossy": + assert _emit(ISONGraph.from_ison(out)) == out + else: + pytest.fail(f"unknown expectation {expectation!r} for {PORT}") diff --git a/vectors/README.md b/vectors/README.md new file mode 100644 index 0000000..9e6c971 --- /dev/null +++ b/vectors/README.md @@ -0,0 +1,10 @@ +# ISONGraph Core Conformance Corpus + +Executable vectors proving "same document -> same meaning in every port". Owned by Core; consumed by ISONGraphExt and downstream at a pinned commit, never copied. + +See `manifest.ison` for the index. Full design: ISONGraphExt blueprint `15-CORE-CONFORMANCE-CORPUS.md`. + +## Findings + +| vector | ports | observed | spec says | status | +|---|---|---|---|---| diff --git a/vectors/ids/positive-int.ison b/vectors/ids/positive-int.ison new file mode 100644 index 0000000..86987e6 --- /dev/null +++ b/vectors/ids/positive-int.ison @@ -0,0 +1,8 @@ +edges.R +source target +:p:1 :p:2 + +nodes.p +id +1 +2 diff --git a/vectors/ids/twin-int-string.ison b/vectors/ids/twin-int-string.ison new file mode 100644 index 0000000..55c7fc1 --- /dev/null +++ b/vectors/ids/twin-int-string.ison @@ -0,0 +1,4 @@ +nodes.p +id +1 +"1" diff --git a/vectors/manifest.ison b/vectors/manifest.ison new file mode 100644 index 0000000..a0a8bde --- /dev/null +++ b/vectors/manifest.ison @@ -0,0 +1,8 @@ +meta.corpus +version semantic_spec +1 "ISONGraph-Semantic/2-draft" + +table.vectors +id file semantic reason directed nodes edges canonical digest python ts js rust cs cpp +ids/positive-int ids/positive-int.ison identifiable null true 2 1 null null pass todo todo todo todo todo +ids/twin-int-string ids/twin-int-string.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" todo todo todo todo todo From a8db626e09bb61a1ececad22269fd0ab6001be2c Mon Sep 17 00:00:00 2001 From: Mahesh VAIKRI Date: Thu, 5 Nov 2026 16:17:47 -0600 Subject: [PATCH 02/11] Add the id vectors: sign, type and twin behaviour on the wire Positive, negative, numeric-string and int64-extreme ids round-trip; int/string twins and float/bool ids are refused as 1.4.1 promises. Co-Authored-By: Claude Fable 5.1 --- vectors/ids/bool-id.ison | 3 +++ vectors/ids/float-id.ison | 3 +++ vectors/ids/int64-extremes.ison | 8 ++++++++ vectors/ids/negative-int.ison | 9 +++++++++ vectors/ids/string-negative.ison | 8 ++++++++ vectors/ids/string-numeric.ison | 8 ++++++++ vectors/ids/twin-negative.ison | 4 ++++ vectors/manifest.ison | 7 +++++++ 8 files changed, 50 insertions(+) create mode 100644 vectors/ids/bool-id.ison create mode 100644 vectors/ids/float-id.ison create mode 100644 vectors/ids/int64-extremes.ison create mode 100644 vectors/ids/negative-int.ison create mode 100644 vectors/ids/string-negative.ison create mode 100644 vectors/ids/string-numeric.ison create mode 100644 vectors/ids/twin-negative.ison diff --git a/vectors/ids/bool-id.ison b/vectors/ids/bool-id.ison new file mode 100644 index 0000000..02983dd --- /dev/null +++ b/vectors/ids/bool-id.ison @@ -0,0 +1,3 @@ +nodes.p +id +true diff --git a/vectors/ids/float-id.ison b/vectors/ids/float-id.ison new file mode 100644 index 0000000..bf0a60b --- /dev/null +++ b/vectors/ids/float-id.ison @@ -0,0 +1,3 @@ +nodes.p +id +1.5 diff --git a/vectors/ids/int64-extremes.ison b/vectors/ids/int64-extremes.ison new file mode 100644 index 0000000..2eb8464 --- /dev/null +++ b/vectors/ids/int64-extremes.ison @@ -0,0 +1,8 @@ +edges.R +source target +:p:-9223372036854775808 :p:9223372036854775807 + +nodes.p +id +-9223372036854775808 +9223372036854775807 diff --git a/vectors/ids/negative-int.ison b/vectors/ids/negative-int.ison new file mode 100644 index 0000000..442fa2d --- /dev/null +++ b/vectors/ids/negative-int.ison @@ -0,0 +1,9 @@ +edges.R +source target +:p:-1 :p:2 +:p:2 :p:-1 + +nodes.p +id +-1 +2 diff --git a/vectors/ids/string-negative.ison b/vectors/ids/string-negative.ison new file mode 100644 index 0000000..a2dede7 --- /dev/null +++ b/vectors/ids/string-negative.ison @@ -0,0 +1,8 @@ +edges.R +source target +:p:-1 :p:2 + +nodes.p +id +"-1" +2 diff --git a/vectors/ids/string-numeric.ison b/vectors/ids/string-numeric.ison new file mode 100644 index 0000000..97f640c --- /dev/null +++ b/vectors/ids/string-numeric.ison @@ -0,0 +1,8 @@ +edges.R +source target +:p:1 :p:2 + +nodes.p +id +"1" +"2" diff --git a/vectors/ids/twin-negative.ison b/vectors/ids/twin-negative.ison new file mode 100644 index 0000000..7a727ba --- /dev/null +++ b/vectors/ids/twin-negative.ison @@ -0,0 +1,4 @@ +nodes.p +id +-1 +"-1" diff --git a/vectors/manifest.ison b/vectors/manifest.ison index a0a8bde..ef386a8 100644 --- a/vectors/manifest.ison +++ b/vectors/manifest.ison @@ -6,3 +6,10 @@ table.vectors id file semantic reason directed nodes edges canonical digest python ts js rust cs cpp ids/positive-int ids/positive-int.ison identifiable null true 2 1 null null pass todo todo todo todo todo ids/twin-int-string ids/twin-int-string.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" todo todo todo todo todo +ids/negative-int ids/negative-int.ison identifiable null true 2 2 null null pass todo todo todo todo todo +ids/string-numeric ids/string-numeric.ison identifiable null true 2 1 null null pass todo todo todo todo todo +ids/string-negative ids/string-negative.ison identifiable null true 2 1 null null pass todo todo todo todo todo +ids/int64-extremes ids/int64-extremes.ison identifiable null true 2 1 null null pass todo todo todo todo todo +ids/twin-negative ids/twin-negative.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" todo todo todo todo todo +ids/float-id ids/float-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" todo todo todo todo todo +ids/bool-id ids/bool-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" todo todo todo todo todo From e8a00f31e70011c8673fa5123840f7413afd0f3f Mon Sep 17 00:00:00 2001 From: Mahesh VAIKRI Date: Thu, 5 Nov 2026 16:18:22 -0600 Subject: [PATCH 03/11] Add the value vectors: numeric normal form, null, Unicode and quoting Pins what the wire carries for 1 vs 1.0, -0.0, int64 edges and beyond, bare nan/inf (strings, which ison-py quotes back out), null elision, NFD vs NFC (kept distinct), typed-looking strings and the quoting rules. Co-Authored-By: Claude Fable 5.1 --- vectors/manifest.ison | 10 ++++++++++ vectors/values/fractional-float.ison | 5 +++++ vectors/values/int-beyond-int64.ison | 3 +++ vectors/values/int-vs-integral-float.ison | 4 ++++ vectors/values/int64-extreme-values.ison | 4 ++++ vectors/values/negative-zero.ison | 3 +++ vectors/values/nfd-vs-nfc.ison | 4 ++++ vectors/values/nonfinite-as-text.canonical.ison | 4 ++++ vectors/values/nonfinite-as-text.ison | 4 ++++ vectors/values/null-elision.ison | 4 ++++ vectors/values/quoting.ison | 3 +++ vectors/values/string-looks-typed.ison | 6 ++++++ 12 files changed, 54 insertions(+) create mode 100644 vectors/values/fractional-float.ison create mode 100644 vectors/values/int-beyond-int64.ison create mode 100644 vectors/values/int-vs-integral-float.ison create mode 100644 vectors/values/int64-extreme-values.ison create mode 100644 vectors/values/negative-zero.ison create mode 100644 vectors/values/nfd-vs-nfc.ison create mode 100644 vectors/values/nonfinite-as-text.canonical.ison create mode 100644 vectors/values/nonfinite-as-text.ison create mode 100644 vectors/values/null-elision.ison create mode 100644 vectors/values/quoting.ison create mode 100644 vectors/values/string-looks-typed.ison diff --git a/vectors/manifest.ison b/vectors/manifest.ison index ef386a8..57db1c0 100644 --- a/vectors/manifest.ison +++ b/vectors/manifest.ison @@ -13,3 +13,13 @@ ids/int64-extremes ids/int64-extremes.ison identifiable null true 2 1 null null ids/twin-negative ids/twin-negative.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" todo todo todo todo todo ids/float-id ids/float-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" todo todo todo todo todo ids/bool-id ids/bool-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" todo todo todo todo todo +values/int-vs-integral-float values/int-vs-integral-float.ison identifiable null true 2 0 null null pass todo todo todo todo todo +values/negative-zero values/negative-zero.ison identifiable null true 1 0 null null pass todo todo todo todo todo +values/fractional-float values/fractional-float.ison identifiable null true 3 0 null null pass todo todo todo todo todo +values/int64-extreme-values values/int64-extreme-values.ison identifiable null true 2 0 null null pass todo todo todo todo todo +values/int-beyond-int64 values/int-beyond-int64.ison out_of_domain INTEGER_OUT_OF_INT64 true 1 0 null null pass todo todo todo todo todo +values/nonfinite-as-text values/nonfinite-as-text.ison identifiable null true 2 0 values/nonfinite-as-text.canonical.ison null "pass:canonicalized" todo todo todo todo todo +values/null-elision values/null-elision.ison identifiable null true 2 0 null null pass todo todo todo todo todo +values/nfd-vs-nfc values/nfd-vs-nfc.ison identifiable null true 2 0 null null pass todo todo todo todo todo +values/string-looks-typed values/string-looks-typed.ison identifiable null true 4 0 null null pass todo todo todo todo todo +values/quoting values/quoting.ison identifiable null true 1 0 null null pass todo todo todo todo todo diff --git a/vectors/values/fractional-float.ison b/vectors/values/fractional-float.ison new file mode 100644 index 0000000..773742e --- /dev/null +++ b/vectors/values/fractional-float.ison @@ -0,0 +1,5 @@ +nodes.p +id x +1 1.5 +2 2.25 +3 0.1 diff --git a/vectors/values/int-beyond-int64.ison b/vectors/values/int-beyond-int64.ison new file mode 100644 index 0000000..aa5d99f --- /dev/null +++ b/vectors/values/int-beyond-int64.ison @@ -0,0 +1,3 @@ +nodes.p +id x +1 100000000000000000000 diff --git a/vectors/values/int-vs-integral-float.ison b/vectors/values/int-vs-integral-float.ison new file mode 100644 index 0000000..b1116e1 --- /dev/null +++ b/vectors/values/int-vs-integral-float.ison @@ -0,0 +1,4 @@ +nodes.p +id x +1 1 +2 1.0 diff --git a/vectors/values/int64-extreme-values.ison b/vectors/values/int64-extreme-values.ison new file mode 100644 index 0000000..3035a38 --- /dev/null +++ b/vectors/values/int64-extreme-values.ison @@ -0,0 +1,4 @@ +nodes.p +id x +1 9223372036854775807 +2 -9223372036854775808 diff --git a/vectors/values/negative-zero.ison b/vectors/values/negative-zero.ison new file mode 100644 index 0000000..0ae27ef --- /dev/null +++ b/vectors/values/negative-zero.ison @@ -0,0 +1,3 @@ +nodes.p +id x +1 -0.0 diff --git a/vectors/values/nfd-vs-nfc.ison b/vectors/values/nfd-vs-nfc.ison new file mode 100644 index 0000000..d421783 --- /dev/null +++ b/vectors/values/nfd-vs-nfc.ison @@ -0,0 +1,4 @@ +nodes.p +id x +1 é +2 é diff --git a/vectors/values/nonfinite-as-text.canonical.ison b/vectors/values/nonfinite-as-text.canonical.ison new file mode 100644 index 0000000..69579f3 --- /dev/null +++ b/vectors/values/nonfinite-as-text.canonical.ison @@ -0,0 +1,4 @@ +nodes.p +id x +1 "nan" +2 "inf" diff --git a/vectors/values/nonfinite-as-text.ison b/vectors/values/nonfinite-as-text.ison new file mode 100644 index 0000000..cce64e4 --- /dev/null +++ b/vectors/values/nonfinite-as-text.ison @@ -0,0 +1,4 @@ +nodes.p +id x +1 nan +2 inf diff --git a/vectors/values/null-elision.ison b/vectors/values/null-elision.ison new file mode 100644 index 0000000..d622e9f --- /dev/null +++ b/vectors/values/null-elision.ison @@ -0,0 +1,4 @@ +nodes.p +id x +1 null +2 1 diff --git a/vectors/values/quoting.ison b/vectors/values/quoting.ison new file mode 100644 index 0000000..336c7f7 --- /dev/null +++ b/vectors/values/quoting.ison @@ -0,0 +1,3 @@ +nodes.d +id a b c d e f +1 "Hello World" a|b "say \"hi\"" "l1\nl2" "" "#x" diff --git a/vectors/values/string-looks-typed.ison b/vectors/values/string-looks-typed.ison new file mode 100644 index 0000000..ce1d198 --- /dev/null +++ b/vectors/values/string-looks-typed.ison @@ -0,0 +1,6 @@ +nodes.p +id x +1 "true" +2 "1" +3 "1.5" +4 "null" From 1c81711a7caf0bbc71b61bf853f3033ae60c690b Mon Sep 17 00:00:00 2001 From: Mahesh VAIKRI Date: Thu, 5 Nov 2026 16:18:48 -0600 Subject: [PATCH 04/11] Add the structure vectors: directedness, mirrors, duplicates, foreign blocks Directed two-way vs undirected mirror pairs no longer share bytes; a mirror pair with conflicting properties is kept as the first mirror; an explicit 'directed true' and an unknown block kind canonicalize away; a MultiGraph document is refused by the simple graph. Co-Authored-By: Claude Fable 5.1 --- vectors/manifest.ison | 9 +++++++++ vectors/structure/directed-duplicate-row.ison | 9 +++++++++ vectors/structure/directed-two-way.ison | 9 +++++++++ vectors/structure/empty.ison | 1 + .../structure/explicit-directed-true.canonical.ison | 3 +++ vectors/structure/explicit-directed-true.ison | 7 +++++++ vectors/structure/multigraph-document.ison | 11 +++++++++++ vectors/structure/self-loop.ison | 7 +++++++ vectors/structure/undirected-basic.ison | 13 +++++++++++++ vectors/structure/undirected-mirror-conflict.ison | 13 +++++++++++++ vectors/structure/unknown-block-kind.canonical.ison | 3 +++ vectors/structure/unknown-block-kind.ison | 7 +++++++ 12 files changed, 92 insertions(+) create mode 100644 vectors/structure/directed-duplicate-row.ison create mode 100644 vectors/structure/directed-two-way.ison create mode 100644 vectors/structure/empty.ison create mode 100644 vectors/structure/explicit-directed-true.canonical.ison create mode 100644 vectors/structure/explicit-directed-true.ison create mode 100644 vectors/structure/multigraph-document.ison create mode 100644 vectors/structure/self-loop.ison create mode 100644 vectors/structure/undirected-basic.ison create mode 100644 vectors/structure/undirected-mirror-conflict.ison create mode 100644 vectors/structure/unknown-block-kind.canonical.ison create mode 100644 vectors/structure/unknown-block-kind.ison diff --git a/vectors/manifest.ison b/vectors/manifest.ison index 57db1c0..913d65d 100644 --- a/vectors/manifest.ison +++ b/vectors/manifest.ison @@ -23,3 +23,12 @@ values/null-elision values/null-elision.ison identifiable null true 2 0 null nul values/nfd-vs-nfc values/nfd-vs-nfc.ison identifiable null true 2 0 null null pass todo todo todo todo todo values/string-looks-typed values/string-looks-typed.ison identifiable null true 4 0 null null pass todo todo todo todo todo values/quoting values/quoting.ison identifiable null true 1 0 null null pass todo todo todo todo todo +structure/directed-two-way structure/directed-two-way.ison identifiable null true 2 2 null null pass todo todo todo todo todo +structure/undirected-basic structure/undirected-basic.ison identifiable null false 2 2 null null pass todo todo todo todo todo +structure/undirected-mirror-conflict structure/undirected-mirror-conflict.ison out_of_domain UNDIRECTED_EDGE_CONFLICT false 2 2 structure/undirected-basic.ison null "pass:canonicalized" todo todo todo todo todo +structure/directed-duplicate-row structure/directed-duplicate-row.ison out_of_domain INVALID_EDGE_ADDRESS true 0 0 null null "reject:DuplicateEdgeError" todo todo todo todo todo +structure/explicit-directed-true structure/explicit-directed-true.ison identifiable null true 1 0 structure/explicit-directed-true.canonical.ison null "pass:canonicalized" todo todo todo todo todo +structure/self-loop structure/self-loop.ison identifiable null true 1 1 null null pass todo todo todo todo todo +structure/multigraph-document structure/multigraph-document.ison out_of_domain MULTIGRAPH_DOCUMENT true 1 1 null null "reject:ValueError" todo todo todo todo todo +structure/unknown-block-kind structure/unknown-block-kind.ison identifiable null true 1 0 structure/unknown-block-kind.canonical.ison null "pass:canonicalized" todo todo todo todo todo +structure/empty structure/empty.ison identifiable null true 0 0 null null pass todo todo todo todo todo diff --git a/vectors/structure/directed-duplicate-row.ison b/vectors/structure/directed-duplicate-row.ison new file mode 100644 index 0000000..d6e081e --- /dev/null +++ b/vectors/structure/directed-duplicate-row.ison @@ -0,0 +1,9 @@ +edges.R +source target +:p:1 :p:2 +:p:1 :p:2 + +nodes.p +id +1 +2 diff --git a/vectors/structure/directed-two-way.ison b/vectors/structure/directed-two-way.ison new file mode 100644 index 0000000..762aff5 --- /dev/null +++ b/vectors/structure/directed-two-way.ison @@ -0,0 +1,9 @@ +edges.R +source target +:p:1 :p:2 +:p:2 :p:1 + +nodes.p +id +1 +2 diff --git a/vectors/structure/empty.ison b/vectors/structure/empty.ison new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/vectors/structure/empty.ison @@ -0,0 +1 @@ + diff --git a/vectors/structure/explicit-directed-true.canonical.ison b/vectors/structure/explicit-directed-true.canonical.ison new file mode 100644 index 0000000..5f47ef3 --- /dev/null +++ b/vectors/structure/explicit-directed-true.canonical.ison @@ -0,0 +1,3 @@ +nodes.p +id +1 diff --git a/vectors/structure/explicit-directed-true.ison b/vectors/structure/explicit-directed-true.ison new file mode 100644 index 0000000..a952b27 --- /dev/null +++ b/vectors/structure/explicit-directed-true.ison @@ -0,0 +1,7 @@ +meta.graph +directed +true + +nodes.p +id +1 diff --git a/vectors/structure/multigraph-document.ison b/vectors/structure/multigraph-document.ison new file mode 100644 index 0000000..ac629ef --- /dev/null +++ b/vectors/structure/multigraph-document.ison @@ -0,0 +1,11 @@ +edges.R +key source target +0 :p:1 :p:1 + +meta.graph +directed format version +true ison-graph-multigraph-v1 1 + +nodes.p +id +1 diff --git a/vectors/structure/self-loop.ison b/vectors/structure/self-loop.ison new file mode 100644 index 0000000..1d092a2 --- /dev/null +++ b/vectors/structure/self-loop.ison @@ -0,0 +1,7 @@ +edges.R +source target +:p:1 :p:1 + +nodes.p +id +1 diff --git a/vectors/structure/undirected-basic.ison b/vectors/structure/undirected-basic.ison new file mode 100644 index 0000000..8fac9ba --- /dev/null +++ b/vectors/structure/undirected-basic.ison @@ -0,0 +1,13 @@ +edges.R +source target w +:p:1 :p:2 1 +:p:2 :p:1 1 + +meta.graph +directed +false + +nodes.p +id +1 +2 diff --git a/vectors/structure/undirected-mirror-conflict.ison b/vectors/structure/undirected-mirror-conflict.ison new file mode 100644 index 0000000..558779e --- /dev/null +++ b/vectors/structure/undirected-mirror-conflict.ison @@ -0,0 +1,13 @@ +edges.R +source target w +:p:1 :p:2 1 +:p:2 :p:1 2 + +meta.graph +directed +false + +nodes.p +id +1 +2 diff --git a/vectors/structure/unknown-block-kind.canonical.ison b/vectors/structure/unknown-block-kind.canonical.ison new file mode 100644 index 0000000..5f47ef3 --- /dev/null +++ b/vectors/structure/unknown-block-kind.canonical.ison @@ -0,0 +1,3 @@ +nodes.p +id +1 diff --git a/vectors/structure/unknown-block-kind.ison b/vectors/structure/unknown-block-kind.ison new file mode 100644 index 0000000..351aaf6 --- /dev/null +++ b/vectors/structure/unknown-block-kind.ison @@ -0,0 +1,7 @@ +table.x +a +1 + +nodes.p +id +1 From 817b01843fe0bb7db5dedee3eace27130a512678 Mon Sep 17 00:00:00 2001 From: Mahesh VAIKRI Date: Thu, 5 Nov 2026 16:19:39 -0600 Subject: [PATCH 05/11] Add the serialization vectors: canonical ordering and ISONL twins A deliberately unsorted document canonicalizes to its sibling, and the ISONL spelling of two existing vectors loads to the same canonical ISON. Co-Authored-By: Claude Fable 5.1 --- vectors/manifest.ison | 3 +++ vectors/serialization/negative-int.isonl | 4 ++++ vectors/serialization/non-canonical-order.canonical.ison | 8 ++++++++ vectors/serialization/non-canonical-order.ison | 8 ++++++++ vectors/serialization/undirected-basic.isonl | 5 +++++ 5 files changed, 28 insertions(+) create mode 100644 vectors/serialization/negative-int.isonl create mode 100644 vectors/serialization/non-canonical-order.canonical.ison create mode 100644 vectors/serialization/non-canonical-order.ison create mode 100644 vectors/serialization/undirected-basic.isonl diff --git a/vectors/manifest.ison b/vectors/manifest.ison index 913d65d..363ab25 100644 --- a/vectors/manifest.ison +++ b/vectors/manifest.ison @@ -32,3 +32,6 @@ structure/self-loop structure/self-loop.ison identifiable null true 1 1 null nul structure/multigraph-document structure/multigraph-document.ison out_of_domain MULTIGRAPH_DOCUMENT true 1 1 null null "reject:ValueError" todo todo todo todo todo structure/unknown-block-kind structure/unknown-block-kind.ison identifiable null true 1 0 structure/unknown-block-kind.canonical.ison null "pass:canonicalized" todo todo todo todo todo structure/empty structure/empty.ison identifiable null true 0 0 null null pass todo todo todo todo todo +serialization/non-canonical-order serialization/non-canonical-order.ison identifiable null true 2 1 serialization/non-canonical-order.canonical.ison null "pass:canonicalized" todo todo todo todo todo +serialization/undirected-basic-isonl serialization/undirected-basic.isonl identifiable null false 2 2 structure/undirected-basic.ison null "pass:canonicalized" todo todo todo todo todo +serialization/negative-int-isonl serialization/negative-int.isonl identifiable null true 2 2 ids/negative-int.ison null "pass:canonicalized" todo todo todo todo todo diff --git a/vectors/serialization/negative-int.isonl b/vectors/serialization/negative-int.isonl new file mode 100644 index 0000000..ff8057e --- /dev/null +++ b/vectors/serialization/negative-int.isonl @@ -0,0 +1,4 @@ +edges.R|source target|:p:-1 :p:2 +edges.R|source target|:p:2 :p:-1 +nodes.p|id|-1 +nodes.p|id|2 diff --git a/vectors/serialization/non-canonical-order.canonical.ison b/vectors/serialization/non-canonical-order.canonical.ison new file mode 100644 index 0000000..ca8fb3d --- /dev/null +++ b/vectors/serialization/non-canonical-order.canonical.ison @@ -0,0 +1,8 @@ +edges.R +source target +:p:1 :p:2 + +nodes.p +id name +1 Alice +2 Bob diff --git a/vectors/serialization/non-canonical-order.ison b/vectors/serialization/non-canonical-order.ison new file mode 100644 index 0000000..0d79b41 --- /dev/null +++ b/vectors/serialization/non-canonical-order.ison @@ -0,0 +1,8 @@ +nodes.p +name id +Bob 2 +Alice 1 + +edges.R +target source +:p:2 :p:1 diff --git a/vectors/serialization/undirected-basic.isonl b/vectors/serialization/undirected-basic.isonl new file mode 100644 index 0000000..f430c1b --- /dev/null +++ b/vectors/serialization/undirected-basic.isonl @@ -0,0 +1,5 @@ +edges.R|source target w|:p:1 :p:2 1 +edges.R|source target w|:p:2 :p:1 1 +meta.graph|directed|false +nodes.p|id|1 +nodes.p|id|2 From ddfd885c0428677195beba04f0791e18098dcbbb Mon Sep 17 00:00:00 2001 From: Mahesh VAIKRI Date: Thu, 5 Nov 2026 16:20:40 -0600 Subject: [PATCH 06/11] Admit the TypeScript port to the conformance corpus Same runner shape as Python, reading the manifest with ison-ts. Setting the ts column from what the port does today records three things worth knowing: it loads a MultiGraph document that every other port refuses, ison-ts writes the string "nan" bare where ison-py quotes it, and ids or values beyond 2^53 come back rounded. Each is in README Findings. Co-Authored-By: Claude Fable 5.1 --- ison-graph-ts/src/vectors.test.ts | 72 +++++++++++++++++++++++++++++++ vectors/README.md | 5 +++ vectors/manifest.ison | 62 +++++++++++++------------- 3 files changed, 108 insertions(+), 31 deletions(-) create mode 100644 ison-graph-ts/src/vectors.test.ts diff --git a/ison-graph-ts/src/vectors.test.ts b/ison-graph-ts/src/vectors.test.ts new file mode 100644 index 0000000..6c44414 --- /dev/null +++ b/ison-graph-ts/src/vectors.test.ts @@ -0,0 +1,72 @@ +/** + * Core Conformance Corpus runner for the TypeScript port. + * Reads vectors/manifest.ison with ison-ts and checks the 'ts' column. + * Grammar and columns: vectors/README.md. + */ +import { describe, it, expect } from 'vitest'; +import { readFileSync } from 'node:fs'; +import { dirname, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parse } from 'ison-ts'; +import { ISONGraph } from './index'; + +const VECTORS = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'vectors'); +const PORT = 'ts'; + +type Row = Record; + +const read = (rel: string): string => readFileSync(resolve(VECTORS, rel), 'utf8'); +const rows: Row[] = parse(read('manifest.ison')).blocks + .filter((b: any) => b.kind === 'table' && b.name === 'vectors') + .flatMap((b: any) => b.rows as Row[]); +const load = (rel: string, text: string): ISONGraph => + rel.endsWith('.isonl') ? ISONGraph.fromIsonl(text) : ISONGraph.fromIson(text); +const emit = (g: ISONGraph): string => g.toIson() + '\n'; + +describe('Core Conformance Corpus (ts)', () => { + it('manifest has rows', () => { + expect(rows.length).toBeGreaterThan(0); + }); + + it('is admitted: no todo in its column', () => { + expect(rows.filter(r => r[PORT] === 'todo').map(r => r.id)).toEqual([]); + }); + + describe.each(rows.map(r => [r.id as string, r] as const))('%s', (_id, row) => { + it('behaves as the manifest says', () => { + const expectation = row[PORT] as string; + const text = read(row.file); + + if (expectation.startsWith('reject:')) { + let name = ''; + try { + load(row.file, text); + } catch (e: any) { + name = e.name ?? e.constructor.name; + } + expect(name).toBe(expectation.slice('reject:'.length)); + return; + } + + const g = load(row.file, text); + expect(g.directed).toBe(row.directed); + expect(g.nodeCount()).toBe(row.nodes); + expect(g.edgeCount()).toBe(row.edges); + + const out = emit(g); + if (expectation === 'defect') { + // Contradicts the spec (README Findings) - pin what the port does. + expect(emit(ISONGraph.fromIson(out))).toBe(out); + } else if (expectation === 'pass') { + expect(out).toBe(text); + } else if (expectation === 'pass:canonicalized') { + expect(out).toBe(read(row.canonical)); + expect(emit(ISONGraph.fromIson(out))).toBe(out); + } else if (expectation === 'pass:lossy') { + expect(emit(ISONGraph.fromIson(out))).toBe(out); + } else { + throw new Error(`unknown expectation ${JSON.stringify(expectation)} for ${PORT}`); + } + }); + }); +}); diff --git a/vectors/README.md b/vectors/README.md index 9e6c971..619ddba 100644 --- a/vectors/README.md +++ b/vectors/README.md @@ -8,3 +8,8 @@ See `manifest.ison` for the index. Full design: ISONGraphExt blueprint `15-CORE- | vector | ports | observed | spec says | status | |---|---|---|---|---| +| structure/multigraph-document | ts, js | loads the document and treats `key` as an edge property | Python, Rust, C# and C++ refuse an `ison-graph-multigraph-v1` document | open - CORE_BLOCKING_DIVERGENCE | +| values/nonfinite-as-text | ts, js | writer emits the strings `nan` / `inf` bare | ison-py quotes them (`"nan"`), so the same graph has two canonical byte forms | open - ISONCS writer divergence, needs an ison-ts/ison-js decision | +| ids/int64-extremes | ts, js | ids beyond 2^53 are read as binary64 and re-emitted rounded | 13-SEMANTIC-2 §1.2 JS binding rule: such input must arrive as BigInt or an exact integer token | known limitation - pass:lossy | +| values/int64-extreme-values | ts, js | as above for property values | as above | known limitation - pass:lossy | +| values/int-vs-integral-float | ts, js | `1.0` is re-emitted as `1` | CHANGELOG 1.4.0 known limitation; Semantic/2 treats both as INT64(1) | known limitation - pass:lossy | diff --git a/vectors/manifest.ison b/vectors/manifest.ison index 363ab25..7742ca9 100644 --- a/vectors/manifest.ison +++ b/vectors/manifest.ison @@ -4,34 +4,34 @@ version semantic_spec table.vectors id file semantic reason directed nodes edges canonical digest python ts js rust cs cpp -ids/positive-int ids/positive-int.ison identifiable null true 2 1 null null pass todo todo todo todo todo -ids/twin-int-string ids/twin-int-string.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" todo todo todo todo todo -ids/negative-int ids/negative-int.ison identifiable null true 2 2 null null pass todo todo todo todo todo -ids/string-numeric ids/string-numeric.ison identifiable null true 2 1 null null pass todo todo todo todo todo -ids/string-negative ids/string-negative.ison identifiable null true 2 1 null null pass todo todo todo todo todo -ids/int64-extremes ids/int64-extremes.ison identifiable null true 2 1 null null pass todo todo todo todo todo -ids/twin-negative ids/twin-negative.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" todo todo todo todo todo -ids/float-id ids/float-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" todo todo todo todo todo -ids/bool-id ids/bool-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" todo todo todo todo todo -values/int-vs-integral-float values/int-vs-integral-float.ison identifiable null true 2 0 null null pass todo todo todo todo todo -values/negative-zero values/negative-zero.ison identifiable null true 1 0 null null pass todo todo todo todo todo -values/fractional-float values/fractional-float.ison identifiable null true 3 0 null null pass todo todo todo todo todo -values/int64-extreme-values values/int64-extreme-values.ison identifiable null true 2 0 null null pass todo todo todo todo todo -values/int-beyond-int64 values/int-beyond-int64.ison out_of_domain INTEGER_OUT_OF_INT64 true 1 0 null null pass todo todo todo todo todo -values/nonfinite-as-text values/nonfinite-as-text.ison identifiable null true 2 0 values/nonfinite-as-text.canonical.ison null "pass:canonicalized" todo todo todo todo todo -values/null-elision values/null-elision.ison identifiable null true 2 0 null null pass todo todo todo todo todo -values/nfd-vs-nfc values/nfd-vs-nfc.ison identifiable null true 2 0 null null pass todo todo todo todo todo -values/string-looks-typed values/string-looks-typed.ison identifiable null true 4 0 null null pass todo todo todo todo todo -values/quoting values/quoting.ison identifiable null true 1 0 null null pass todo todo todo todo todo -structure/directed-two-way structure/directed-two-way.ison identifiable null true 2 2 null null pass todo todo todo todo todo -structure/undirected-basic structure/undirected-basic.ison identifiable null false 2 2 null null pass todo todo todo todo todo -structure/undirected-mirror-conflict structure/undirected-mirror-conflict.ison out_of_domain UNDIRECTED_EDGE_CONFLICT false 2 2 structure/undirected-basic.ison null "pass:canonicalized" todo todo todo todo todo -structure/directed-duplicate-row structure/directed-duplicate-row.ison out_of_domain INVALID_EDGE_ADDRESS true 0 0 null null "reject:DuplicateEdgeError" todo todo todo todo todo -structure/explicit-directed-true structure/explicit-directed-true.ison identifiable null true 1 0 structure/explicit-directed-true.canonical.ison null "pass:canonicalized" todo todo todo todo todo -structure/self-loop structure/self-loop.ison identifiable null true 1 1 null null pass todo todo todo todo todo -structure/multigraph-document structure/multigraph-document.ison out_of_domain MULTIGRAPH_DOCUMENT true 1 1 null null "reject:ValueError" todo todo todo todo todo -structure/unknown-block-kind structure/unknown-block-kind.ison identifiable null true 1 0 structure/unknown-block-kind.canonical.ison null "pass:canonicalized" todo todo todo todo todo -structure/empty structure/empty.ison identifiable null true 0 0 null null pass todo todo todo todo todo -serialization/non-canonical-order serialization/non-canonical-order.ison identifiable null true 2 1 serialization/non-canonical-order.canonical.ison null "pass:canonicalized" todo todo todo todo todo -serialization/undirected-basic-isonl serialization/undirected-basic.isonl identifiable null false 2 2 structure/undirected-basic.ison null "pass:canonicalized" todo todo todo todo todo -serialization/negative-int-isonl serialization/negative-int.isonl identifiable null true 2 2 ids/negative-int.ison null "pass:canonicalized" todo todo todo todo todo +ids/positive-int ids/positive-int.ison identifiable null true 2 1 null null pass pass todo todo todo todo +ids/twin-int-string ids/twin-int-string.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" "reject:DuplicateNodeError" todo todo todo todo +ids/negative-int ids/negative-int.ison identifiable null true 2 2 null null pass pass todo todo todo todo +ids/string-numeric ids/string-numeric.ison identifiable null true 2 1 null null pass pass todo todo todo todo +ids/string-negative ids/string-negative.ison identifiable null true 2 1 null null pass pass todo todo todo todo +ids/int64-extremes ids/int64-extremes.ison identifiable null true 2 1 null null pass "pass:lossy" todo todo todo todo +ids/twin-negative ids/twin-negative.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" "reject:DuplicateNodeError" todo todo todo todo +ids/float-id ids/float-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" "reject:InvalidIdentifierError" todo todo todo todo +ids/bool-id ids/bool-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" "reject:InvalidIdentifierError" todo todo todo todo +values/int-vs-integral-float values/int-vs-integral-float.ison identifiable null true 2 0 null null pass "pass:lossy" todo todo todo todo +values/negative-zero values/negative-zero.ison identifiable null true 1 0 null null pass pass todo todo todo todo +values/fractional-float values/fractional-float.ison identifiable null true 3 0 null null pass pass todo todo todo todo +values/int64-extreme-values values/int64-extreme-values.ison identifiable null true 2 0 null null pass "pass:lossy" todo todo todo todo +values/int-beyond-int64 values/int-beyond-int64.ison out_of_domain INTEGER_OUT_OF_INT64 true 1 0 null null pass pass todo todo todo todo +values/nonfinite-as-text values/nonfinite-as-text.ison identifiable null true 2 0 values/nonfinite-as-text.canonical.ison null "pass:canonicalized" pass todo todo todo todo +values/null-elision values/null-elision.ison identifiable null true 2 0 null null pass pass todo todo todo todo +values/nfd-vs-nfc values/nfd-vs-nfc.ison identifiable null true 2 0 null null pass pass todo todo todo todo +values/string-looks-typed values/string-looks-typed.ison identifiable null true 4 0 null null pass pass todo todo todo todo +values/quoting values/quoting.ison identifiable null true 1 0 null null pass pass todo todo todo todo +structure/directed-two-way structure/directed-two-way.ison identifiable null true 2 2 null null pass pass todo todo todo todo +structure/undirected-basic structure/undirected-basic.ison identifiable null false 2 2 null null pass pass todo todo todo todo +structure/undirected-mirror-conflict structure/undirected-mirror-conflict.ison out_of_domain UNDIRECTED_EDGE_CONFLICT false 2 2 structure/undirected-basic.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo +structure/directed-duplicate-row structure/directed-duplicate-row.ison out_of_domain INVALID_EDGE_ADDRESS true 0 0 null null "reject:DuplicateEdgeError" "reject:DuplicateEdgeError" todo todo todo todo +structure/explicit-directed-true structure/explicit-directed-true.ison identifiable null true 1 0 structure/explicit-directed-true.canonical.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo +structure/self-loop structure/self-loop.ison identifiable null true 1 1 null null pass pass todo todo todo todo +structure/multigraph-document structure/multigraph-document.ison out_of_domain MULTIGRAPH_DOCUMENT true 1 1 null null "reject:ValueError" defect todo todo todo todo +structure/unknown-block-kind structure/unknown-block-kind.ison identifiable null true 1 0 structure/unknown-block-kind.canonical.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo +structure/empty structure/empty.ison identifiable null true 0 0 null null pass pass todo todo todo todo +serialization/non-canonical-order serialization/non-canonical-order.ison identifiable null true 2 1 serialization/non-canonical-order.canonical.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo +serialization/undirected-basic-isonl serialization/undirected-basic.isonl identifiable null false 2 2 structure/undirected-basic.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo +serialization/negative-int-isonl serialization/negative-int.isonl identifiable null true 2 2 ids/negative-int.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo From c75dfda758d8059ad98942f2bfacb91aa1223520 Mon Sep 17 00:00:00 2001 From: Mahesh VAIKRI Date: Thu, 5 Nov 2026 16:21:46 -0600 Subject: [PATCH 07/11] Admit the JavaScript port to the conformance corpus Mirror of the TypeScript runner against ison-parser. The js column matches ts everywhere, which is the point: the two ports share one writer design and the corpus now proves it per document. Co-Authored-By: Claude Fable 5.1 --- ison-graph-js/src/vectors.test.js | 70 +++++++++++++++++++++++++++++++ vectors/manifest.ison | 62 +++++++++++++-------------- 2 files changed, 101 insertions(+), 31 deletions(-) create mode 100644 ison-graph-js/src/vectors.test.js diff --git a/ison-graph-js/src/vectors.test.js b/ison-graph-js/src/vectors.test.js new file mode 100644 index 0000000..6dbea10 --- /dev/null +++ b/ison-graph-js/src/vectors.test.js @@ -0,0 +1,70 @@ +/** + * Core Conformance Corpus runner for the JavaScript port. + * Reads vectors/manifest.ison with ison-parser and checks the 'js' column. + * Grammar and columns: vectors/README.md. + */ +import { describe, it, expect } from 'vitest'; +import { readFileSync } from 'node:fs'; +import { dirname, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { loads as parse } from 'ison-parser'; +import { ISONGraph } from './index.js'; + +const VECTORS = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'vectors'); +const PORT = 'js'; + +const read = (rel) => readFileSync(resolve(VECTORS, rel), 'utf8'); +const rows = parse(read('manifest.ison')).blocks + .filter((b) => b.kind === 'table' && b.name === 'vectors') + .flatMap((b) => b.rows); +const load = (rel, text) => + rel.endsWith('.isonl') ? ISONGraph.fromIsonl(text) : ISONGraph.fromIson(text); +const emit = (g) => g.toIson() + '\n'; + +describe('Core Conformance Corpus (js)', () => { + it('manifest has rows', () => { + expect(rows.length).toBeGreaterThan(0); + }); + + it('is admitted: no todo in its column', () => { + expect(rows.filter((r) => r[PORT] === 'todo').map((r) => r.id)).toEqual([]); + }); + + describe.each(rows.map((r) => [r.id, r]))('%s', (_id, row) => { + it('behaves as the manifest says', () => { + const expectation = row[PORT]; + const text = read(row.file); + + if (expectation.startsWith('reject:')) { + let name = ''; + try { + load(row.file, text); + } catch (e) { + name = e.name ?? e.constructor.name; + } + expect(name).toBe(expectation.slice('reject:'.length)); + return; + } + + const g = load(row.file, text); + expect(g.directed).toBe(row.directed); + expect(g.nodeCount()).toBe(row.nodes); + expect(g.edgeCount()).toBe(row.edges); + + const out = emit(g); + if (expectation === 'defect') { + // Contradicts the spec (README Findings) - pin what the port does. + expect(emit(ISONGraph.fromIson(out))).toBe(out); + } else if (expectation === 'pass') { + expect(out).toBe(text); + } else if (expectation === 'pass:canonicalized') { + expect(out).toBe(read(row.canonical)); + expect(emit(ISONGraph.fromIson(out))).toBe(out); + } else if (expectation === 'pass:lossy') { + expect(emit(ISONGraph.fromIson(out))).toBe(out); + } else { + throw new Error(`unknown expectation ${JSON.stringify(expectation)} for ${PORT}`); + } + }); + }); +}); diff --git a/vectors/manifest.ison b/vectors/manifest.ison index 7742ca9..1f7b05f 100644 --- a/vectors/manifest.ison +++ b/vectors/manifest.ison @@ -4,34 +4,34 @@ version semantic_spec table.vectors id file semantic reason directed nodes edges canonical digest python ts js rust cs cpp -ids/positive-int ids/positive-int.ison identifiable null true 2 1 null null pass pass todo todo todo todo -ids/twin-int-string ids/twin-int-string.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" "reject:DuplicateNodeError" todo todo todo todo -ids/negative-int ids/negative-int.ison identifiable null true 2 2 null null pass pass todo todo todo todo -ids/string-numeric ids/string-numeric.ison identifiable null true 2 1 null null pass pass todo todo todo todo -ids/string-negative ids/string-negative.ison identifiable null true 2 1 null null pass pass todo todo todo todo -ids/int64-extremes ids/int64-extremes.ison identifiable null true 2 1 null null pass "pass:lossy" todo todo todo todo -ids/twin-negative ids/twin-negative.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" "reject:DuplicateNodeError" todo todo todo todo -ids/float-id ids/float-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" "reject:InvalidIdentifierError" todo todo todo todo -ids/bool-id ids/bool-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" "reject:InvalidIdentifierError" todo todo todo todo -values/int-vs-integral-float values/int-vs-integral-float.ison identifiable null true 2 0 null null pass "pass:lossy" todo todo todo todo -values/negative-zero values/negative-zero.ison identifiable null true 1 0 null null pass pass todo todo todo todo -values/fractional-float values/fractional-float.ison identifiable null true 3 0 null null pass pass todo todo todo todo -values/int64-extreme-values values/int64-extreme-values.ison identifiable null true 2 0 null null pass "pass:lossy" todo todo todo todo -values/int-beyond-int64 values/int-beyond-int64.ison out_of_domain INTEGER_OUT_OF_INT64 true 1 0 null null pass pass todo todo todo todo -values/nonfinite-as-text values/nonfinite-as-text.ison identifiable null true 2 0 values/nonfinite-as-text.canonical.ison null "pass:canonicalized" pass todo todo todo todo -values/null-elision values/null-elision.ison identifiable null true 2 0 null null pass pass todo todo todo todo -values/nfd-vs-nfc values/nfd-vs-nfc.ison identifiable null true 2 0 null null pass pass todo todo todo todo -values/string-looks-typed values/string-looks-typed.ison identifiable null true 4 0 null null pass pass todo todo todo todo -values/quoting values/quoting.ison identifiable null true 1 0 null null pass pass todo todo todo todo -structure/directed-two-way structure/directed-two-way.ison identifiable null true 2 2 null null pass pass todo todo todo todo -structure/undirected-basic structure/undirected-basic.ison identifiable null false 2 2 null null pass pass todo todo todo todo -structure/undirected-mirror-conflict structure/undirected-mirror-conflict.ison out_of_domain UNDIRECTED_EDGE_CONFLICT false 2 2 structure/undirected-basic.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo -structure/directed-duplicate-row structure/directed-duplicate-row.ison out_of_domain INVALID_EDGE_ADDRESS true 0 0 null null "reject:DuplicateEdgeError" "reject:DuplicateEdgeError" todo todo todo todo -structure/explicit-directed-true structure/explicit-directed-true.ison identifiable null true 1 0 structure/explicit-directed-true.canonical.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo -structure/self-loop structure/self-loop.ison identifiable null true 1 1 null null pass pass todo todo todo todo -structure/multigraph-document structure/multigraph-document.ison out_of_domain MULTIGRAPH_DOCUMENT true 1 1 null null "reject:ValueError" defect todo todo todo todo -structure/unknown-block-kind structure/unknown-block-kind.ison identifiable null true 1 0 structure/unknown-block-kind.canonical.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo -structure/empty structure/empty.ison identifiable null true 0 0 null null pass pass todo todo todo todo -serialization/non-canonical-order serialization/non-canonical-order.ison identifiable null true 2 1 serialization/non-canonical-order.canonical.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo -serialization/undirected-basic-isonl serialization/undirected-basic.isonl identifiable null false 2 2 structure/undirected-basic.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo -serialization/negative-int-isonl serialization/negative-int.isonl identifiable null true 2 2 ids/negative-int.ison null "pass:canonicalized" "pass:canonicalized" todo todo todo todo +ids/positive-int ids/positive-int.ison identifiable null true 2 1 null null pass pass pass todo todo todo +ids/twin-int-string ids/twin-int-string.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" "reject:DuplicateNodeError" "reject:DuplicateNodeError" todo todo todo +ids/negative-int ids/negative-int.ison identifiable null true 2 2 null null pass pass pass todo todo todo +ids/string-numeric ids/string-numeric.ison identifiable null true 2 1 null null pass pass pass todo todo todo +ids/string-negative ids/string-negative.ison identifiable null true 2 1 null null pass pass pass todo todo todo +ids/int64-extremes ids/int64-extremes.ison identifiable null true 2 1 null null pass "pass:lossy" "pass:lossy" todo todo todo +ids/twin-negative ids/twin-negative.ison out_of_domain AMBIGUOUS_NODE_REFERENCE true 0 0 null null "reject:DuplicateNodeError" "reject:DuplicateNodeError" "reject:DuplicateNodeError" todo todo todo +ids/float-id ids/float-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" "reject:InvalidIdentifierError" "reject:InvalidIdentifierError" todo todo todo +ids/bool-id ids/bool-id.ison out_of_domain INVALID_NODE_ID_TYPE true 0 0 null null "reject:InvalidIdentifierError" "reject:InvalidIdentifierError" "reject:InvalidIdentifierError" todo todo todo +values/int-vs-integral-float values/int-vs-integral-float.ison identifiable null true 2 0 null null pass "pass:lossy" "pass:lossy" todo todo todo +values/negative-zero values/negative-zero.ison identifiable null true 1 0 null null pass pass pass todo todo todo +values/fractional-float values/fractional-float.ison identifiable null true 3 0 null null pass pass pass todo todo todo +values/int64-extreme-values values/int64-extreme-values.ison identifiable null true 2 0 null null pass "pass:lossy" "pass:lossy" todo todo todo +values/int-beyond-int64 values/int-beyond-int64.ison out_of_domain INTEGER_OUT_OF_INT64 true 1 0 null null pass pass pass todo todo todo +values/nonfinite-as-text values/nonfinite-as-text.ison identifiable null true 2 0 values/nonfinite-as-text.canonical.ison null "pass:canonicalized" pass pass todo todo todo +values/null-elision values/null-elision.ison identifiable null true 2 0 null null pass pass pass todo todo todo +values/nfd-vs-nfc values/nfd-vs-nfc.ison identifiable null true 2 0 null null pass pass pass todo todo todo +values/string-looks-typed values/string-looks-typed.ison identifiable null true 4 0 null null pass pass pass todo todo todo +values/quoting values/quoting.ison identifiable null true 1 0 null null pass pass pass todo todo todo +structure/directed-two-way structure/directed-two-way.ison identifiable null true 2 2 null null pass pass pass todo todo todo +structure/undirected-basic structure/undirected-basic.ison identifiable null false 2 2 null null pass pass pass todo todo todo +structure/undirected-mirror-conflict structure/undirected-mirror-conflict.ison out_of_domain UNDIRECTED_EDGE_CONFLICT false 2 2 structure/undirected-basic.ison null "pass:canonicalized" "pass:canonicalized" "pass:canonicalized" todo todo todo +structure/directed-duplicate-row structure/directed-duplicate-row.ison out_of_domain INVALID_EDGE_ADDRESS true 0 0 null null "reject:DuplicateEdgeError" "reject:DuplicateEdgeError" "reject:DuplicateEdgeError" todo todo todo +structure/explicit-directed-true structure/explicit-directed-true.ison identifiable null true 1 0 structure/explicit-directed-true.canonical.ison null "pass:canonicalized" "pass:canonicalized" "pass:canonicalized" todo todo todo +structure/self-loop structure/self-loop.ison identifiable null true 1 1 null null pass pass pass todo todo todo +structure/multigraph-document structure/multigraph-document.ison out_of_domain MULTIGRAPH_DOCUMENT true 1 1 null null "reject:ValueError" defect defect todo todo todo +structure/unknown-block-kind structure/unknown-block-kind.ison identifiable null true 1 0 structure/unknown-block-kind.canonical.ison null "pass:canonicalized" "pass:canonicalized" "pass:canonicalized" todo todo todo +structure/empty structure/empty.ison identifiable null true 0 0 null null pass pass pass todo todo todo +serialization/non-canonical-order serialization/non-canonical-order.ison identifiable null true 2 1 serialization/non-canonical-order.canonical.ison null "pass:canonicalized" "pass:canonicalized" "pass:canonicalized" todo todo todo +serialization/undirected-basic-isonl serialization/undirected-basic.isonl identifiable null false 2 2 structure/undirected-basic.ison null "pass:canonicalized" "pass:canonicalized" "pass:canonicalized" todo todo todo +serialization/negative-int-isonl serialization/negative-int.isonl identifiable null true 2 2 ids/negative-int.ison null "pass:canonicalized" "pass:canonicalized" "pass:canonicalized" todo todo todo From 69f4b6309468710e05c32eabe08ee1bf9547f75c Mon Sep 17 00:00:00 2001 From: Mahesh VAIKRI Date: Thu, 5 Nov 2026 16:22:57 -0600 Subject: [PATCH 08/11] Add the corpus digest ISONGraphExt pins SHA-256 over the sorted (path, bytes) of vectors/**, so a consumer can state exactly which corpus it was proven against without copying it. Co-Authored-By: Claude Fable 5.1 --- ison-graph/tests/test_corpus_scripts.py | 60 +++++++++++++++++++++++++ scripts/corpus_digest.py | 44 ++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 ison-graph/tests/test_corpus_scripts.py create mode 100644 scripts/corpus_digest.py diff --git a/ison-graph/tests/test_corpus_scripts.py b/ison-graph/tests/test_corpus_scripts.py new file mode 100644 index 0000000..1a9feba --- /dev/null +++ b/ison-graph/tests/test_corpus_scripts.py @@ -0,0 +1,60 @@ +"""Tests for the repo-level corpus scripts (scripts/corpus_digest.py and +scripts/corpus_receipt.py). They live outside the package, so they are +imported by path.""" + +from __future__ import annotations + +import hashlib +import importlib.util +import re +import sys +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[2] +SCRIPTS = ROOT / "scripts" + + +def _import(name: str): + spec = importlib.util.spec_from_file_location(name, SCRIPTS / f"{name}.py") + module = importlib.util.module_from_spec(spec) + sys.modules[name] = module + spec.loader.exec_module(module) + return module + + +digest_mod = _import("corpus_digest") + + +def _make(tmp_path: Path, files: dict[str, bytes]) -> Path: + for rel, data in files.items(): + p = tmp_path / rel + p.parent.mkdir(parents=True, exist_ok=True) + p.write_bytes(data) + return tmp_path + + +def test_digest_is_sha256_over_sorted_path_and_bytes(tmp_path): + root = _make(tmp_path, {"b/two.ison": b"2\n", "a.ison": b"1\n"}) + expected = hashlib.sha256(b"a.ison\0" + b"1\n" + b"\0" + b"b/two.ison\0" + b"2\n" + b"\0").hexdigest() + assert digest_mod.corpus_digest(root) == expected + + +def test_digest_ignores_creation_order(tmp_path): + a = _make(tmp_path / "x", {"a.ison": b"1\n", "b.ison": b"2\n"}) + b = _make(tmp_path / "y", {"b.ison": b"2\n", "a.ison": b"1\n"}) + assert digest_mod.corpus_digest(a) == digest_mod.corpus_digest(b) + + +def test_digest_changes_when_a_byte_changes(tmp_path): + root = _make(tmp_path, {"a.ison": b"1\n"}) + before = digest_mod.corpus_digest(root) + (root / "a.ison").write_bytes(b"1 \n") + assert digest_mod.corpus_digest(root) != before + + +def test_real_corpus_digest_is_stable_across_two_calls(): + d1 = digest_mod.corpus_digest(ROOT / "vectors") + d2 = digest_mod.corpus_digest(ROOT / "vectors") + assert d1 == d2 and len(d1) == 64 diff --git a/scripts/corpus_digest.py b/scripts/corpus_digest.py new file mode 100644 index 0000000..3af716c --- /dev/null +++ b/scripts/corpus_digest.py @@ -0,0 +1,44 @@ +#!/usr/bin/env python3 +"""Print the digest ISONGraphExt pins as core_vector_corpus_digest. + + sha256( concat over sorted relative paths of: path + "\\0" + bytes + "\\0" ) + +Sorted by POSIX relative path so the result is the same on every platform +and independent of checkout order. Usage: + + python scripts/corpus_digest.py # defaults to /vectors + python scripts/corpus_digest.py some/dir +""" + +from __future__ import annotations + +import hashlib +import sys +from pathlib import Path + + +def corpus_digest(root: Path) -> str: + h = hashlib.sha256() + # Sort by the exact key that is hashed - the POSIX relative path - so the + # order never depends on platform path semantics or Path ordering rules. + files = sorted( + (p for p in root.rglob("*") if p.is_file()), + key=lambda p: p.relative_to(root).as_posix(), + ) + for path in files: + rel = path.relative_to(root).as_posix().encode("utf-8") + h.update(rel + b"\0" + path.read_bytes() + b"\0") + return h.hexdigest() + + +def main(argv: list[str]) -> int: + root = Path(argv[1]) if len(argv) > 1 else Path(__file__).resolve().parents[1] / "vectors" + if not root.is_dir(): + print(f"not a directory: {root}", file=sys.stderr) + return 2 + print(corpus_digest(root)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv)) From fd53cd44ce80fcb782ca505e68fa5d6b1ba1adce Mon Sep 17 00:00:00 2001 From: Mahesh VAIKRI Date: Thu, 5 Nov 2026 16:24:08 -0600 Subject: [PATCH 09/11] Emit a Core Conformance Receipt per port A corpus digest says which corpus a port was proven against, not how it did. The receipt adds the port's posture - FULL, LOSSY_KNOWN, KNOWN_DEFECT, PARTIAL or INCONCLUSIVE - derived from the manifest it is bound to, with the counts behind it and full commit SHAs, so a downstream consumer can refuse identity claims through a lossy or defective port instead of discovering the problem later. Co-Authored-By: Claude Fable 5.1 --- ison-graph/tests/test_corpus_scripts.py | 48 +++++++++ scripts/corpus_receipt.py | 125 ++++++++++++++++++++++++ 2 files changed, 173 insertions(+) create mode 100644 scripts/corpus_receipt.py diff --git a/ison-graph/tests/test_corpus_scripts.py b/ison-graph/tests/test_corpus_scripts.py index 1a9feba..974cb02 100644 --- a/ison-graph/tests/test_corpus_scripts.py +++ b/ison-graph/tests/test_corpus_scripts.py @@ -58,3 +58,51 @@ def test_real_corpus_digest_is_stable_across_two_calls(): d1 = digest_mod.corpus_digest(ROOT / "vectors") d2 = digest_mod.corpus_digest(ROOT / "vectors") assert d1 == d2 and len(d1) == 64 + + +receipt_mod = _import("corpus_receipt") + + +@pytest.mark.parametrize("cells,runner,expected", [ + (["pass", "reject:X", "pass:canonicalized"], True, "FULL"), + (["pass", "pass:lossy"], True, "LOSSY_KNOWN"), + (["pass", "defect"], True, "KNOWN_DEFECT"), + (["pass:lossy", "defect"], True, "KNOWN_DEFECT"), + (["todo", "todo"], False, "PARTIAL"), + (["pass", "todo"], True, "INCONCLUSIVE"), + (["pass"], False, "INCONCLUSIVE"), +]) +def test_posture(cells, runner, expected): + assert receipt_mod.posture(cells, runner) == expected + + +def test_receipt_for_python_is_full_and_counts_add_up(): + r = receipt_mod.build_receipt(ROOT, "python") + assert r["port"] == "python" + assert r["core_format"] == "isongraph" + assert r["semantic_spec"] == "ISONGraph-Semantic/2-draft" + assert r["corpus_version"] == 1 + assert len(r["corpus_digest"]) == 64 + assert re.fullmatch(r"[0-9a-f]{40}", r["core_commit"]) + assert re.fullmatch(r"[0-9a-f]{40}", r["corpus_commit"]) + assert r["posture"] == "FULL" + assert r["total"] == r["pass"] + r["canonicalized"] + r["lossy"] + r["defect"] + r["rejected_as_expected"] + r["todo"] + assert r["todo"] == 0 + + +def test_receipt_for_ts_is_known_defect(): + r = receipt_mod.build_receipt(ROOT, "ts") + assert r["posture"] == "KNOWN_DEFECT" + assert r["defect"] >= 1 and r["lossy"] >= 1 + + +def test_receipt_for_rust_is_partial(): + r = receipt_mod.build_receipt(ROOT, "rust") + assert r["posture"] == "PARTIAL" and r["todo"] == r["total"] + + +def test_receipt_cli_prints_ison(capsys): + assert receipt_mod.main(["corpus_receipt.py", "--port", "python"]) == 0 + out = capsys.readouterr().out + assert out.startswith("meta.core_conformance_receipt\n") + assert " FULL" in out diff --git a/scripts/corpus_receipt.py b/scripts/corpus_receipt.py new file mode 100644 index 0000000..7a18daf --- /dev/null +++ b/scripts/corpus_receipt.py @@ -0,0 +1,125 @@ +#!/usr/bin/env python3 +"""Emit the Core Conformance Receipt for one port, as ISON. + +The receipt is computed from vectors/manifest.ison - whose expectations are +observed behaviour by the corpus rules - plus the port's declared version +and the repo's git state. The port's runner is what makes the manifest +trustworthy, so a receipt is only meaningful for a commit whose CI is +green. Posture is derived, never hand-set: + + FULL runner exists, no todo, no pass:lossy, no defect + LOSSY_KNOWN runner exists, no todo, no defect, some pass:lossy + KNOWN_DEFECT runner exists, no todo, some defect (contradicts the spec) + PARTIAL no runner (every cell todo) + INCONCLUSIVE manifest and runner disagree about admission + +Commits are full SHAs: the receipt is a long-lived pin. + +Usage: + python scripts/corpus_receipt.py --port python +""" + +from __future__ import annotations + +import argparse +import json +import re +import subprocess +import sys +from pathlib import Path + +from ison_parser import Block, Document, dumps_canonical, loads + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +from corpus_digest import corpus_digest # noqa: E402 + +RUNNERS = { + "python": "ison-graph/tests/test_vectors.py", + "ts": "ison-graph-ts/src/vectors.test.ts", + "js": "ison-graph-js/src/vectors.test.js", + "rust": "ison-graph-rs/tests/vectors.rs", + "cs": "ison-graph-cs/tests/IsonGraph.Tests/VectorsTests.cs", + "cpp": "ison-graph-cpp/tests/test_vectors.cpp", +} + +VERSION_FILES = { + "python": ("ison-graph/pyproject.toml", r'^version = "([^"]+)"'), + "ts": ("ison-graph-ts/package.json", None), + "js": ("ison-graph-js/package.json", None), + "rust": ("ison-graph-rs/Cargo.toml", r'^version = "([^"]+)"'), + "cs": ("ison-graph-cs/src/IsonGraph/IsonGraph.csproj", r"([^<]+)"), + "cpp": ("ison-graph-cpp/CMakeLists.txt", r"VERSION ([0-9.]+) "), +} + + +def posture(cells: list[str], runner_exists: bool) -> str: + todo = sum(c == "todo" for c in cells) + if not runner_exists: + return "PARTIAL" if todo == len(cells) else "INCONCLUSIVE" + if todo: + return "INCONCLUSIVE" + if any(c == "defect" for c in cells): + return "KNOWN_DEFECT" + if any(c == "pass:lossy" for c in cells): + return "LOSSY_KNOWN" + return "FULL" + + +def port_version(root: Path, port: str) -> str: + rel, pattern = VERSION_FILES[port] + text = (root / rel).read_text(encoding="utf-8") + if pattern is None: + return json.loads(text)["version"] + m = re.search(pattern, text, flags=re.M) + if not m: + raise SystemExit(f"no version in {rel}") + return m.group(1) + + +def git(root: Path, *args: str) -> str: + return subprocess.check_output(["git", *args], cwd=root, text=True).strip() + + +def build_receipt(root: Path, port: str) -> dict: + manifest = loads((root / "vectors" / "manifest.ison").read_text(encoding="utf-8")) + meta = next(b for b in manifest.blocks if b.kind == "meta" and b.name == "corpus").rows[0] + rows = [r for b in manifest.blocks if b.kind == "table" and b.name == "vectors" for r in b.rows] + cells = [r[port] for r in rows] + runner_exists = (root / RUNNERS[port]).is_file() + return { + "core_format": "isongraph", + "core_version": port_version(root, "python"), + "core_commit": git(root, "rev-parse", "HEAD"), + "semantic_spec": meta["semantic_spec"], + "corpus_version": meta["version"], + "corpus_commit": git(root, "log", "-1", "--format=%H", "--", "vectors") or git(root, "rev-parse", "HEAD"), + "corpus_digest": corpus_digest(root / "vectors"), + "port": port, + "port_version": port_version(root, port), + "total": len(cells), + "pass": sum(c == "pass" for c in cells), + "canonicalized": sum(c == "pass:canonicalized" for c in cells), + "lossy": sum(c == "pass:lossy" for c in cells), + "defect": sum(c == "defect" for c in cells), + "rejected_as_expected": sum(c.startswith("reject:") for c in cells), + "todo": sum(c == "todo" for c in cells), + "posture": posture(cells, runner_exists), + } + + +def to_ison(receipt: dict) -> str: + block = Block(kind="meta", name="core_conformance_receipt", fields=list(receipt), rows=[receipt]) + return dumps_canonical(Document(blocks=[block])) + + +def main(argv: list[str]) -> int: + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument("--port", required=True, choices=sorted(RUNNERS)) + parser.add_argument("--root", default=str(Path(__file__).resolve().parents[1])) + args = parser.parse_args(argv[1:]) + print(to_ison(build_receipt(Path(args.root), args.port))) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv)) From 4b92a84bd9b01113c80f229ebcdcaefdc456d88d Mon Sep 17 00:00:00 2001 From: Mahesh VAIKRI Date: Thu, 5 Nov 2026 16:24:42 -0600 Subject: [PATCH 10/11] Document the corpus and record what it found README carries the manifest schema, the expectation grammar and the Findings table the meta-test enforces; the changelog entry names the three divergences the corpus surfaced on day one. Co-Authored-By: Claude Fable 5.1 --- CHANGELOG.md | 17 ++++++++++++ vectors/README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 86 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f7f623a..e867a6d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,23 @@ share this file and, from 1.3.0, a single version number. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Added + +- **Core Conformance Corpus** (`vectors/`): 31 executable ISON/ISONL + documents with a per-port expectation each, run by the Python, TypeScript + and JavaScript suites on every push. One golden fixture used to be the only + thing saying the ports agree; the corpus says it per document, and records + where they still do not (`vectors/README.md` § Findings): TS/JS accept a + MultiGraph document the other four ports refuse, ison-ts/ison-js write the + string `nan` bare where ison-py quotes it, and ids or values beyond 2^53 + come back rounded in TS/JS. Rust, C# and C++ columns are `todo` until each + gets a runner - admission is all-or-nothing per port. +- `scripts/corpus_digest.py` and `scripts/corpus_receipt.py`, which produce + what ISONGraphExt pins: the corpus digest and a per-port Core Conformance + Receipt with a derived posture. + ## [1.4.1] — 2026-11-05 Four ways a graph's meaning changed between `dump` and `load`, found while diff --git a/vectors/README.md b/vectors/README.md index 619ddba..397c7a4 100644 --- a/vectors/README.md +++ b/vectors/README.md @@ -1,8 +1,75 @@ # ISONGraph Core Conformance Corpus -Executable vectors proving "same document -> same meaning in every port". Owned by Core; consumed by ISONGraphExt and downstream at a pinned commit, never copied. +Executable vectors proving **"same document → same meaning in every port"**. +Owned by Core. ISONGraphExt, ISONGraph Visualize and products consume it at a +pinned commit through the Core Conformance Receipt; they never copy or fork +it. A missing vector is added here. -See `manifest.ison` for the index. Full design: ISONGraphExt blueprint `15-CORE-CONFORMANCE-CORPUS.md`. +## What it tests + +Documents. Each vector is an ISON or ISONL text; each port loads it, checks +directedness and counts, writes it back and compares bytes. Construction-time +API refusals (NaN at `add_node`, float ids, property-name rules) cannot be +carried on the wire and are each port's unit tests, not this corpus. + +Expected Semantic/2 digests are not yet included; the `digest` column is +reserved and `null`. + +## Layout + + manifest.ison the only index; every port parses it with its own ISON parser + ids/ values/ structure/ serialization/ + ../scripts/corpus_digest.py sha256 over sorted (path, bytes) of vectors/** + ../scripts/corpus_receipt.py per-port Core Conformance Receipt + +Every file is UTF-8 without BOM, LF-only, ending in exactly one newline; the +`.gitattributes` rule `vectors/** text eol=lf` keeps it so on every platform. +Comparison is always `to_ison() + "\n"` against the file. A file ending in +`.isonl` is loaded with `from_isonl`. + +## Manifest columns + +| column | meaning | +|---|---| +| `id` | `/`, unique | +| `file` | path relative to this directory | +| `semantic` | `identifiable` or `out_of_domain` under ISONGraph-Semantic/2 | +| `reason` | why out of domain; `null` when identifiable | +| `directed` | expected `graph.directed` after load | +| `nodes`, `edges` | expected counts after load; `edges` counts stored records (an undirected edge counts 2) | +| `canonical` | sibling file holding the canonical output when the input is deliberately non-canonical; set iff some port is `pass:canonicalized` | +| `digest` | reserved; `null` | +| `python` `ts` `js` `rust` `cs` `cpp` | per-port expectation, below | + +## Per-port expectation grammar + +| value | the runner checks | +|---|---| +| `pass` | loads; directed and counts match; output is byte-identical to the file | +| `pass:canonicalized` | loads; counts match; output equals the `canonical` file and is idempotent | +| `pass:lossy` | loads; counts match; output differs for a documented port limitation; idempotent | +| `defect` | loads without raising but contradicts the spec; directed and counts are pinned to what the port does and output must be idempotent; a Findings row below must name the vector | +| `reject:` | loading raises that port's error class of that name | +| `todo` | no runner for this port yet | + +Rules. Expectations are set from **observed** behaviour of the released port; +an observation that contradicts Semantic/2 becomes a Findings row, never a +weakened vector. **Port runner admission is atomic**: a column contains +`todo` iff the port's runner file is absent, so a port is either fully in or +not in. **Three postures never collapse**: `python = pass` on +`values/int-beyond-int64` says the port loads it; `semantic = out_of_domain` +says Semantic/2 assigns it no identity. `pass:lossy` is not conformance — a +consumer needing cross-port identity treats that port as `CORE_LOSSY` for the +input. + +## Receipt + +`python scripts/corpus_receipt.py --port ` prints one `meta.core_conformance_receipt` +row: core commit and version, semantic spec, corpus version/commit/digest, +port and version, the counts per expectation kind, and the derived posture +(`FULL`, `LOSSY_KNOWN`, `KNOWN_DEFECT`, `PARTIAL`, `INCONCLUSIVE`). Commits are +full SHAs. `NONCONFORMANT` is CI's verdict, not the script's: a receipt is +only meaningful for a green commit. ## Findings From f88af8bd29680e7b6e7716585be936d5738eb55f Mon Sep 17 00:00:00 2001 From: Mahesh VAIKRI Date: Thu, 5 Nov 2026 16:37:46 -0600 Subject: [PATCH 11/11] Make 'pass:lossy' prove the loss, and pin an inexact beyond-int64 value Review findings. A 'pass:lossy' cell only checked idempotence, so a port that later preserved the input would keep reporting a loss forever; all three runners now also assert the output differs from the file. And the 10^20 vector read as "TS/JS keep integers beyond int64", which is false: that literal is exactly representable in binary64. A companion vector with 10^20 + 1 records the rounding, and the Findings row for the MultiGraph defect now says that TS/JS also drop meta.graph on output. Co-Authored-By: Claude Fable 5.1 --- CHANGELOG.md | 10 ++++++---- ison-graph-js/src/vectors.test.js | 3 +++ ison-graph-ts/src/vectors.test.ts | 3 +++ ison-graph/tests/test_vectors.py | 3 +++ vectors/README.md | 3 ++- vectors/manifest.ison | 1 + vectors/values/int-beyond-int64-inexact.ison | 3 +++ 7 files changed, 21 insertions(+), 5 deletions(-) create mode 100644 vectors/values/int-beyond-int64-inexact.ison diff --git a/CHANGELOG.md b/CHANGELOG.md index e867a6d..bbcd356 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,10 +15,12 @@ and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html). and JavaScript suites on every push. One golden fixture used to be the only thing saying the ports agree; the corpus says it per document, and records where they still do not (`vectors/README.md` § Findings): TS/JS accept a - MultiGraph document the other four ports refuse, ison-ts/ison-js write the - string `nan` bare where ison-py quotes it, and ids or values beyond 2^53 - come back rounded in TS/JS. Rust, C# and C++ columns are `todo` until each - gets a runner - admission is all-or-nothing per port. + MultiGraph document that Python refuses (and that Rust, C# and C++ refuse + by their own unit tests - their corpus runners are still to come), + ison-ts/ison-js write the string `nan` bare where ison-py quotes it, and + ids or values beyond 2^53 come back rounded in TS/JS unless the value + happens to be exactly representable in binary64. Rust, C# and C++ columns + are `todo` until each gets a runner - admission is all-or-nothing per port. - `scripts/corpus_digest.py` and `scripts/corpus_receipt.py`, which produce what ISONGraphExt pins: the corpus digest and a per-port Core Conformance Receipt with a derived posture. diff --git a/ison-graph-js/src/vectors.test.js b/ison-graph-js/src/vectors.test.js index 6dbea10..3fed465 100644 --- a/ison-graph-js/src/vectors.test.js +++ b/ison-graph-js/src/vectors.test.js @@ -61,6 +61,9 @@ describe('Core Conformance Corpus (js)', () => { expect(out).toBe(read(row.canonical)); expect(emit(ISONGraph.fromIson(out))).toBe(out); } else if (expectation === 'pass:lossy') { + // The loss must be real: if the port now preserves the input, the + // cell is stale and should become 'pass'. + expect(out, 'pass:lossy but output equals the file - promote the cell to pass').not.toBe(text); expect(emit(ISONGraph.fromIson(out))).toBe(out); } else { throw new Error(`unknown expectation ${JSON.stringify(expectation)} for ${PORT}`); diff --git a/ison-graph-ts/src/vectors.test.ts b/ison-graph-ts/src/vectors.test.ts index 6c44414..394fdfd 100644 --- a/ison-graph-ts/src/vectors.test.ts +++ b/ison-graph-ts/src/vectors.test.ts @@ -63,6 +63,9 @@ describe('Core Conformance Corpus (ts)', () => { expect(out).toBe(read(row.canonical)); expect(emit(ISONGraph.fromIson(out))).toBe(out); } else if (expectation === 'pass:lossy') { + // The loss must be real: if the port now preserves the input, the + // cell is stale and should become 'pass'. + expect(out, 'pass:lossy but output equals the file - promote the cell to pass').not.toBe(text); expect(emit(ISONGraph.fromIson(out))).toBe(out); } else { throw new Error(`unknown expectation ${JSON.stringify(expectation)} for ${PORT}`); diff --git a/ison-graph/tests/test_vectors.py b/ison-graph/tests/test_vectors.py index 79d856e..12df4e7 100644 --- a/ison-graph/tests/test_vectors.py +++ b/ison-graph/tests/test_vectors.py @@ -139,6 +139,9 @@ def test_vector(row): assert out == _read(row["canonical"]) assert _emit(ISONGraph.from_ison(out)) == out elif expectation == "pass:lossy": + # The loss must be real: if the port now preserves the input, the + # cell is stale and should become 'pass'. + assert out != text, "pass:lossy but output equals the file - promote the cell to pass" assert _emit(ISONGraph.from_ison(out)) == out else: pytest.fail(f"unknown expectation {expectation!r} for {PORT}") diff --git a/vectors/README.md b/vectors/README.md index 397c7a4..173f869 100644 --- a/vectors/README.md +++ b/vectors/README.md @@ -75,8 +75,9 @@ only meaningful for a green commit. | vector | ports | observed | spec says | status | |---|---|---|---|---| -| structure/multigraph-document | ts, js | loads the document and treats `key` as an edge property | Python, Rust, C# and C++ refuse an `ison-graph-multigraph-v1` document | open - CORE_BLOCKING_DIVERGENCE | +| structure/multigraph-document | ts, js | loads the document, treats `key` as an edge property, and drops the whole `meta.graph` block on output - so a TS/JS round trip turns a multigraph document into a simple-graph document that Python then accepts | Python, Rust, C# and C++ refuse an `ison-graph-multigraph-v1` document | open - CORE_BLOCKING_DIVERGENCE | | values/nonfinite-as-text | ts, js | writer emits the strings `nan` / `inf` bare | ison-py quotes them (`"nan"`), so the same graph has two canonical byte forms | open - ISONCS writer divergence, needs an ison-ts/ison-js decision | | ids/int64-extremes | ts, js | ids beyond 2^53 are read as binary64 and re-emitted rounded | 13-SEMANTIC-2 §1.2 JS binding rule: such input must arrive as BigInt or an exact integer token | known limitation - pass:lossy | | values/int64-extreme-values | ts, js | as above for property values | as above | known limitation - pass:lossy | +| values/int-beyond-int64-inexact | ts, js | `100000000000000000001` is read as binary64 and re-emitted as `100000000000000000000`; the sibling `values/int-beyond-int64` (10^20) is `pass` only because that literal is exactly representable | as above - integers beyond 2^53 are not preserved unless exactly representable | known limitation - pass:lossy | | values/int-vs-integral-float | ts, js | `1.0` is re-emitted as `1` | CHANGELOG 1.4.0 known limitation; Semantic/2 treats both as INT64(1) | known limitation - pass:lossy | diff --git a/vectors/manifest.ison b/vectors/manifest.ison index 1f7b05f..469ca4c 100644 --- a/vectors/manifest.ison +++ b/vectors/manifest.ison @@ -18,6 +18,7 @@ values/negative-zero values/negative-zero.ison identifiable null true 1 0 null n values/fractional-float values/fractional-float.ison identifiable null true 3 0 null null pass pass pass todo todo todo values/int64-extreme-values values/int64-extreme-values.ison identifiable null true 2 0 null null pass "pass:lossy" "pass:lossy" todo todo todo values/int-beyond-int64 values/int-beyond-int64.ison out_of_domain INTEGER_OUT_OF_INT64 true 1 0 null null pass pass pass todo todo todo +values/int-beyond-int64-inexact values/int-beyond-int64-inexact.ison out_of_domain INTEGER_OUT_OF_INT64 true 1 0 null null pass "pass:lossy" "pass:lossy" todo todo todo values/nonfinite-as-text values/nonfinite-as-text.ison identifiable null true 2 0 values/nonfinite-as-text.canonical.ison null "pass:canonicalized" pass pass todo todo todo values/null-elision values/null-elision.ison identifiable null true 2 0 null null pass pass pass todo todo todo values/nfd-vs-nfc values/nfd-vs-nfc.ison identifiable null true 2 0 null null pass pass pass todo todo todo diff --git a/vectors/values/int-beyond-int64-inexact.ison b/vectors/values/int-beyond-int64-inexact.ison new file mode 100644 index 0000000..27f72c3 --- /dev/null +++ b/vectors/values/int-beyond-int64-inexact.ison @@ -0,0 +1,3 @@ +nodes.p +id x +1 100000000000000000001