# goldengraph-native

> PyO3 binding for goldengraph-core: resolution-merged knowledge graph + neighborhood retrieval.

## What this package is

A compiled companion wheel for **goldengraph**. You do not import it directly --
`goldengraph` discovers it at runtime. This directory contains a compiled abi3
extension and almost no readable Python, so reading it will not tell you what it does.

## Authoritative sources

Read these instead of inferring behaviour from the binary or from the host's fallback path:

- https://github.com/benseverndev-oss/goldenmatch/tree/main/packages/python/goldengraph -- documentation for this surface.
- `goldengraph/llms.txt` -- ships inside the goldengraph wheel (`Path(goldengraph.__file__).parent / "llms.txt"`), written for machine readers.
- https://docs.bensevern.dev/docs/llms.txt -- index of every Golden Suite surface.
- https://github.com/benseverndev-oss/goldenmatch -- source, issues, and the decision records behind the behaviour.

## Install

```bash
pip install goldengraph[native]   # pulls goldengraph-native
```

## Runtime gate

- `GOLDENGRAPH_NATIVE=auto` (default) -- use the kernel where it exists, fall back otherwise.
- `GOLDENGRAPH_NATIVE=0` -- force-disable the whole engine. There is no pure-Python fallback, so callers raise a clear error rather than silently degrading.
- `GOLDENGRAPH_NATIVE=1` -- require the kernel; raise if it is missing.

Discovery lives in `goldengraph.core._native_loader`.

## Notes

- NOT an optional accelerator -- there is no pure-Python fallback for the store and resolution engine. GoldenGraph's compute is Rust-only.
- The Python surface is a JSON boundary (`build_graph_json`, `neighborhood_json`, `store_append_json`, ...) mirroring the WASM and C-ABI surfaces exactly, so all three runtimes are byte-identical by construction.

This wheel exists because a behaviour was *decided* -- which surface owns a computation,
which fallback is deliberate, which parity is contract-tested. Those decisions are
documented; the compiled artefact cannot tell you about them.
