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/CHANGELOG.md b/CHANGELOG.md index f7f623a..bbcd356 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,25 @@ 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 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. + ## [1.4.1] — 2026-11-05 Four ways a graph's meaning changed between `dump` and `load`, found while diff --git a/ison-graph-js/src/vectors.test.js b/ison-graph-js/src/vectors.test.js new file mode 100644 index 0000000..3fed465 --- /dev/null +++ b/ison-graph-js/src/vectors.test.js @@ -0,0 +1,73 @@ +/** + * 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') { + // 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 new file mode 100644 index 0000000..394fdfd --- /dev/null +++ b/ison-graph-ts/src/vectors.test.ts @@ -0,0 +1,75 @@ +/** + * 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') { + // 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_corpus_scripts.py b/ison-graph/tests/test_corpus_scripts.py new file mode 100644 index 0000000..974cb02 --- /dev/null +++ b/ison-graph/tests/test_corpus_scripts.py @@ -0,0 +1,108 @@ +"""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 + + +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/ison-graph/tests/test_vectors.py b/ison-graph/tests/test_vectors.py new file mode 100644 index 0000000..12df4e7 --- /dev/null +++ b/ison-graph/tests/test_vectors.py @@ -0,0 +1,147 @@ +"""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": + # 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/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)) 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)) diff --git a/vectors/README.md b/vectors/README.md new file mode 100644 index 0000000..173f869 --- /dev/null +++ b/vectors/README.md @@ -0,0 +1,83 @@ +# ISONGraph Core Conformance Corpus + +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. + +## 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 + +| vector | ports | observed | spec says | status | +|---|---|---|---|---| +| 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/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/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/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-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/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 new file mode 100644 index 0000000..469ca4c --- /dev/null +++ b/vectors/manifest.ison @@ -0,0 +1,38 @@ +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 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/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 +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 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 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 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-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 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"