isongraph-ext

Prove what a graph is, where it came from, and how to show it — without changing the graph.

ISONGraph stores a graph as a compact, token-efficient file. That file deliberately says nothing about who made it, where its facts came from, or how a viewer should draw it. isongraph-ext answers those three questions with small companion files that sit next to the graph and are tied to its exact bytes by SHA-256. The graph itself is never modified, and everything works offline.

graph.ison          the ordinary ISONGraph; Core reads it exactly as before
  |-- graph.igx.ison    IGX/1   binding      "is this the graph I was promised?"
  |-- graph.igpv.ison  IGPV/1  provenance   "where did this come from?"
  `-- graph.igdm.ison  IGDM/1  datamatics   "how should a viewer present it?"

Each companion is optional and independent. A consumer that knows none of them still has the whole graph.

Install

pip install isongraph-ext

Python 3.12+. Pure Python. The only dependencies are ison-graph==1.4.1 and ison-py==1.2.0, pinned exactly, because the package verifies against the Core baseline it was measured with.

Try it

Bind a graph to its bytes, verify it, then change one byte:

from ison_graph import ISONGraph
from isongraph_ext import igx

g = ISONGraph()
g.add_node("person", "ada", name="Ada")
g.add_node("person", "grace", name="Grace")
g.add_edge("knows", ("person", "ada"), ("person", "grace"))
data = g.to_ison().encode("utf-8")

binding = igx.bind(data, serialization_profile="ison-v1", producer_port="python", identity_claim="artifact")
result, decision = igx.verify_and_admit(binding, data)
print("admitted:", decision.admitted, "| steps:", ", ".join(result.steps_passed))

try:
    igx.verify(binding, data + b"\n# edited")
except igx.IGXError as e:
    print("tampered:", e.code, "at", e.step)

admitted: True | steps: V0, V1, V2, V3, V4, V5
tampered: SOURCE_BINDING_MISMATCH at V4

Verification is a fixed sequence of numbered steps, and every failure names the step and a stable error code.

Command line

python -m isongraph_ext.igx   verify graph.ison graph.igx.ison                  # exit 0 ok, 1 invalid, 64 usage
python -m isongraph_ext.igx   admit  graph.ison graph.igx.ison                  # exit 0 admitted, 2 denied
python -m isongraph_ext.igpv  verify graph.ison graph.igx.ison graph.igpv.ison [--source SHA256=PATH]
python -m isongraph_ext.igpv  origins <graph-sha256> graph.igpv.ison --node person ada
python -m isongraph_ext.igdm  verify graph.ison graph.igx.ison graph.igdm.ison

Output is itself ISON, so receipts can quote it verbatim.

What you get

Built to be checked

• Byte-exact. Companion files are canonical by construction: one graph, one companion, one set of bytes, one SHA-256.
• Specified before coded. Frozen specifications for IGX/1, IGPV/1 and IGDM/1 live in the repository; the code follows them, never the reverse.
• Conformance vectors. 156 byte-exact vectors and about 450 tests are replayed in CI on every change.
• Pinned to a measured Core. The package embeds the Core baseline it was verified against, plus Core's conformance receipts, so identity claims are checkable rather than asserted.
• Hostile-input safe. Parsing is bounded by explicit size and row budgets; verification reports the first failing step instead of guessing.

Examples

Four runnable demonstrations (a non-software provenance graph, a supply-chain presentation graph, a minimal generic SVG adapter and a Core-only consumer) are in the examples folder of the repository.

Status and limits

This is an early-stage (alpha) release. Know what it does not do:

• A verified binding proves reproducibility and consistency, not authorship; producer_port is a checked claim, not authentication.
• Provenance proves origin and lineage, not that an extracted statement is true.
• The cross-port identity claim and lossy producer-bound admission are reserved. Revision, delta, projection and DAG capabilities are not implemented.
• IGDM/1 carries presentation intent only and renders nothing.
• Python reference implementation only. Verification is an offline cost: roughly 5 seconds for a 10,000-node graph with a capability.

Links

Source and issues · Changelog · Security policy · ISONGraph Core

MIT — Copyright (c) 2026 Mahesh Vaikri.