ISONGraphExt

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

Try it · What you get · CLI · Examples · Where it fits · Architecture · Status · Specs

---

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. ISONGraphExt 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.

flowchart LR
    G["<b>graph.ison</b><br/>an ordinary ISONGraph<br/>(Core reads it as before)"]
    X["<b>graph.igx.ison</b><br/>IGX/1 · binding"]
    P["<b>graph.igpv.ison</b><br/>IGPV/1 · provenance"]
    D["<b>graph.igdm.ison</b><br/>IGDM/1 · datamatics"]
    G -. "SHA-256" .- X
    G -. "SHA-256" .- P
    G -. "SHA-256" .- D
    X --> V{{"verify · admit"}}
    P --> V
    D --> V

Loading

Core works without any of it. Add a companion only when you need the answer it gives.

What you get

Question	Capability	In one line
Is this really the graph I was promised?	IGX/1 binding	Pins the exact bytes, the Core version they were written with, and an identity claim (none, artifact, producer_bound). Unknown capabilities are reported or refused, never silently ignored.
Where did this come from?	IGPV/1 provenance	Attributes nodes and edges to source documents, with byte or line spans you can check against the real bytes, and records derivation lineage: this node stands for those nodes in an earlier graph.
How should a viewer present it?	IGDM/1 datamatics	Renderer-neutral presentation intent: semantic roles, emphasis, badges, groups, layout hints and accessibility text. Never colours, fonts or coordinates.
Which part of this graph do I need?	IGP/1 projection	Selects a bounded, deterministic subgraph from explicit anchors, relation and type allow-lists, direction, depth and budgets, and returns an ordinary graph plus provenance for every node and edge. Anyone can recompute it from the source and the policy.

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

Try it in two minutes

pip install isongraph-ext

Python 3.12+; the only dependencies are ison-graph==1.4.1 and ison-py==1.2.0. To run the bundled examples or work on the code, install from a clone instead:

git clone https://github.com/ISON-format/isongraph-ext.git && cd isongraph-ext
python -m venv .venv && . .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e isongraph-ext                         # editable install; ison-graph and ison-py are pulled in

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.

Project a bounded subgraph

Select what an agent, a report or a viewer needs, with proof of where every part came from:

from ison_graph import ISONGraph
from isongraph_ext.igp import Policy, project
from isongraph_ext.igpv import NodeRef

g = ISONGraph()
for name in ("ada", "grace", "linus"):
    g.add_node("person", name)
g.add_edge("knows", ("person", "ada"), ("person", "grace"))
g.add_edge("knows", ("person", "grace"), ("person", "linus"))
data = g.to_ison().encode("utf-8")

policy = Policy(anchors=(NodeRef("person", "ada"),), direction="out", depth=1)
result = project(data, policy)
print("selected:", result.stats["selected_nodes"], "nodes,", result.stats["result_edges"], "edge")
print("lineage rows:", len(result.payload.derivations), "| policy digest:", result.policy_sha256[:12])

selected: 2 nodes, 1 edge
lineage rows: 3 | policy digest: 2b7fbfb0ce34

The policy is a canonical file you can keep next to the graph (policy.to_ison()); its digest is recorded in the lineage. result.result_bytes is an ordinary ISONGraph, result.payload an IGPV/1 lineage payload, and verify_projection recomputes both from the source and the policy. The policy never inspects property values: you choose the anchors, IGP/1 does the structural work. Specification: 21-IGP1-DESIGN.md.

From the command line

python examples/supply_chain_assets.py --write out/      # makes a graph, a binding and a datamatics payload
python -m isongraph_ext.igx verify out/assets.ison out/assets.igx.ison

meta.verification
binding_digest semantic_verification source_canonical source_semantic_eligibility source_semantic_reason steps_passed unrecognized_optional
7057257e8d09a62d5c0a03ec2983bd38155e6579e04a1446c62116c45009c292 full "true" eligible null V0,V1,V2,V3,V4,V5 x-asset-ledger

Output is itself ISON, so receipts can quote it verbatim. Exit codes are stable: 0 ok, 1 invalid, 2 admission denied, 64 usage.

python -m isongraph_ext.igx   admit  out/assets.ison out/assets.igx.ison
python -m isongraph_ext.igdm  verify out/assets.ison out/assets.igx.ison out/assets.igdm.ison
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.igp   project graph.ison policy.igp.ison --out out/       # writes result.ison and result.igpv.ison
python -m isongraph_ext.igp   verify  graph.ison policy.igp.ison result.ison result.igpv.ison

Examples

Runnable demonstrations that use only the public API. Neither involves software.

Example	What it shows
institutional_evidence.py	Board minutes become decisions and evidence. Provenance links each node to the exact lines it came from, rejects a tampered source, and traces a merged decision back to the raw rows it replaced.
supply_chain_assets.py	Suppliers, facilities and components with regions, a bill of materials and visual states carried as datamatics. Also lists what the contract cannot express.
igdm_to_svg.py	A deliberately tiny, generic consumer: verify first, then draw a static SVG from the closed role vocabulary. Unknown x- roles are ignored, not interpreted.
core_only.py	A consumer that never imports the extension package. The graph is just a graph.

See examples/README.md for how to run them, the timings, and what they do not prove.

Where it fits

Layer	Owns
ISONGraph Core	The graph: nodes, edges, properties, parsing and writing
ISONGraphExt (this repository)	Binding, provenance and presentation intent as verifiable companion files
ISONGraph Visualize	Layout, interaction, animation and rendering of datamatics
Your application	Domain meaning, policy and user experience

Ext never reinterprets the document, and it carries no vocabulary from any one domain.

Architecture

ISONGraphExt is an offline Python library with CLI entry points. The graph stays in Core; extensions live in companion files. The following overview shows how producers, artifacts, verification and consumers connect.

Files and responsibilities

An application uses ISONGraph Core to produce graph.ison, containing nodes, edges and properties. It can then add the companions it needs:

File	Responsibility	What connects it to the graph
graph.igx.ison	Binding: records the Core baseline, conformance receipt, identity claim and declared capabilities.	SHA-256 of the exact graph bytes. Capability rows also pin the bytes of declared payloads.
graph.igpv.ison	Provenance: records source artifacts, producers, object attributions and derivation lineage.	Target graph digest and serialization profile; its payload digest is declared in IGX.
graph.igdm.ison	Presentation intent: describes roles, emphasis, badges, groups, layout hints and accessibility text.	Target graph digest and serialization profile; its payload digest is declared in IGX.

IGPV and IGDM are independently optional; neither requires the other. Their verification APIs require an IGX binding. A Core-only consumer can read the original graph without loading any extension.

Verification and admission flow

The schematic expands the implementation into its verification stages, shared support modules and consumer boundary. Open the image for full-size detail, or use the editable SVG.

1. Produce and bind. Create the graph, serialize any payloads, and create an IGX binding that records their digests. The graph bytes are unchanged.
2. Verify the binding. IGX checks the runtime, binding shape, Core baseline, receipt references, source bytes and capability support through V0–V5. Shared support includes embedded baselines and receipts, canonical ISON serialization, SHA-256 and a capability registry.
3. Verify each supplied payload. IGPV runs P0–P5 to check the payload binding, structure, references, graph objects and supplied source locators. IGDM runs D0–D4 to check its binding, structure, references and graph objects. Each payload verifier invokes IGX verification itself. Byte and row budgets bound input processing; unavailable provenance evidence remains explicitly unverified.
4. Apply admission policy. verify_and_admit passes the fresh verification result into admission: A1 checks baseline currency, A2 checks whether the identity claim is admissible, and A3 reports consumer posture. Successful verification and permission to use the binding are separate results.
5. Consume the result. Applications decide how to use the reports and admission decision. Viewers combine the graph with verified IGDM intent and choose layout, styling and interaction. Rendering belongs to the consumer; Ext supplies no renderer.

The reference runtime pins ison-graph==1.4.1 and ison-py==1.2.0. These checks establish byte consistency and checkable lineage; they do not authenticate authorship or establish that source statements are true. See the architecture notes for source references and verification-order details, and the normative specifications for the complete contracts.

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. Each capability has a frozen specification in docs/blueprint/; the code follows it, never the reverse.
• Conformance vectors. 217 byte-exact vectors in vectors/ (IGX/1 35, IGPV/1 71, IGDM/1 50, IGP/1 61) and about 590 tests, replayed in CI on every change.
• Pinned to a measured Core. The package embeds the Core baseline it was verified against, plus Core's own conformance receipts, so identity claims are checkable rather than asserted.
• Limits stated plainly. IGPV/1, IGDM/1 and IGP/1 enforce explicit input-size and row limits; IGX/1 does not define equivalent limits. Large or untrusted inputs can use a lot of memory and time, because byte limits do not bound memory. Apply your own process-level resource controls (measurements and guidance). Verification reports the first failing step instead of guessing.

Status and limits

ISONGraphExt is an early-stage (alpha) release, published on PyPI as isongraph-ext. 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; a SHA-256 identifies bytes without authenticating where they came from.
• The cross-port identity claim and lossy producer-bound admission are reserved. Revision, delta and DAG capabilities are not implemented. Projection is structural only (no property filters) and supports directed simple graphs.
• IGDM/1 carries presentation intent only and renders nothing.
• It is a Python reference implementation. Verification is an offline cost: roughly 2 seconds for a 10,000-node graph with a capability (see examples/README.md).
• The examples were verified on Windows and in Linux CI, not on macOS.

Documentation

docs/blueprint/ holds the normative texts: the Ext/Core contract (16), IGX/1 (17), IGPV/1 (18), IGDM/1 (19) and IGP/1 (21). CHANGELOG.md lists what changed, CONTRIBUTING.md explains how to work on the project and how releases are made, and SECURITY.md explains how to report a vulnerability privately.

License

MIT — Copyright (c) 2026 Mahesh Vaikri. See LICENSE.