graviti-engine

The deterministic scoring engine behind Graviti — trust infrastructure for agent-mediated commerce, built by Singulariti. This repository exists so the site's central claim ("scoring is open to audit") is checkable, not just stated: src/engine.ts here is the exact module that ranks every recommendation in production — the MCP servers, the web console, and the public endpoints all import this one file. There is no private ranking path.

Use it from any agent — under a minute

Graviti speaks MCP on two paths; both serve the same seven tools (match_intent, get_verified_claims, category_landscape, get_accountability_log, get_ledger, get_gap_report, report_conversion) through this exact engine.

Remote (fastest) — hosted Streamable HTTP endpoint, no auth, no account:

{ "mcpServers": { "graviti": { "url": "https://graviti.thesingulariti.ai/api/mcp" } } }

Local — the graviti-mcp npm package over stdio:

{ "mcpServers": { "graviti": { "command": "npx", "args": ["-y", "graviti-mcp"] } } }

The package ships an index snapshot and, on startup, pulls the latest published index and verifies it against the signed ledger — the pinned key, two independent ledger paths, and the replay guard are the same procedure as scripts/verify-payload.mjs below. A tampered or replayed payload is never used. (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; wiring for other clients at graviti.thesingulariti.ai/use-graviti.)

The two laws

1. Verification is paid. Ranking is never paid. Brands pay for continuous independent auditing of their claims. Verification status carries zero weight in ranking — read the fit-score construction in matchIntent() and confirm no payment signal enters it.
2. Payment buys speed, never outcome. A brand can pay to fast-track a re-evaluation; payment compresses the clock, never the verdict.

The only score adjustments tied to a brand's standing are the fixed, disclosed lifecycle penalties (LIFECYCLE_PENALTY: flagged −0.05, degraded −0.15) — driven by monitored quality signals, never by payment status — and revoked brands are excluded from scoring entirely.

What you can verify by reading this code

• Scoring is deterministic. Pure functions over a brand index — no I/O, no network, no randomness, no learned parameters. The engine's only inputs are the index, the question text, and an optional intent profile. Same inputs, same scores, every time.
• Conversion data never enters scoring. The engine has no conversion input — grep this file for anything conversion-shaped and you'll find nothing. Attributed-conversion events exist in the private transport layer purely as billing records (pay-on-real-acquisition); they are structurally incapable of reaching a fit score because this module never sees them.
• Scores are reproducible from public data. The full index this engine runs over in production is public. Point the engine at it and you reproduce production scores exactly:
  • https://graviti.thesingulariti.ai/index.json — manifest (totals, disclosure, category list)
  • https://graviti.thesingulariti.ai/index-full.json — the complete index in one fetch; this is the exact content the integrity ledger hashes
  • https://graviti.thesingulariti.ai/ledger.json — append-only, hash-chained, Ed25519-signed, Bitcoin-anchored version history
• Every payload carries structural disclosure. See disclosure(): rank_influenced_by_payment: false, who paid, who didn't, and what payment buys — machine-readable, on every response.
• Out-of-scope questions get a refusal, never a guess. See the in_index: false branch of matchIntent().

Run it

npm install
npm run demo -- "best magnesium supplement"
npm run demo -- "cheapest cold plunge with a chiller"
npm run demo -- "best magnesium supplement" --json     # the full machine payload agents receive

The demo runs the engine over data/sample-index.json, a small real slice of the public index (five categories, ~100 brands, with claims, provenance URLs, and the accountability log). For the complete picture, fetch index-full.json and substitute it — the engine takes any BrandIndex.

Verify the ledger

The index's version history is a hash chain: each entry commits to the SHA-256 of the canonical full-index content and the previous entry's hash, is Ed25519-signed against the published public key (data/public-key.pem, also served at /public-key.pem), and is anchored to Bitcoin via OpenTimestamps. Rewriting any historical entry breaks every hash after it — even Graviti cannot edit the record.

npm run verify:ledger           # verifies the committed ledger snapshot, then checks it against the live index
npm run verify:ledger -- --live # fetches and verifies the current live ledger instead

The script needs no secrets and no Graviti-run infrastructure: it recomputes every entry hash, walks the chain back to genesis, and checks every signature against the public key. Bitcoin anchors can be independently replayed with the open-source OpenTimestamps client against proofs at /ots/v<N>.ots — instructions in llms.txt.

Verify what you received — transport integrity

The ledger proves what was published. It cannot see the pipe: TLS-terminating proxies, CDNs, caches, and load balancers sit between Graviti's origin and your process, and any of them could alter a payload with no ledger entry capturing the delta. From ledger v25, every entry's signed core pins a sha256 manifest of every published payload (files.artifacts), so the check moves to your side of the pipe. Verify before trust:

npm run verify:payload                                             # /index-full.json
npm run verify:payload -- /index.json /data/categories/magnesium-supplements.json /llms.txt

scripts/verify-payload.mjs is dependency-free (Node ≥ 20) and exits nonzero on any failure. It:

1. fetches the ledger from two independent paths — this repo's snapshot on raw.githubusercontent.com and the origin's /ledger.json — verifies both chains, and cross-checks the heads (a fork or an origin serving an older ledger than the public mirror fails loudly);
2. verifies every Ed25519 signature against the pinned signing key embedded in the script — the served /public-key.pem is cross-checked against the pin and a mismatch is a failure, never a source of trust;
3. recomputes the sha256 of the payload you actually received and compares it to the head entry's signed manifest;
4. guards against replay: a payload that matches an older entry's manifest instead of the head is stale-but-validly-signed — reported as its own failure, because a replayed yesterday is the subtle attack.

No Node? The core check is two commands with curl, jq, and sha256sum — expected hash from the mirror snapshot (independent path), actual hash from the bytes that reached you:

curl -s https://raw.githubusercontent.com/sclaytonmyosin/graviti-engine/main/data/ledger.json \
  | jq -r '.entries[-1].files.artifacts["/index-full.json"]'
curl -s https://graviti.thesingulariti.ai/index-full.json \
  | jq -cjS 'del(.generated_at, .integrity)' | sha256sum

The two hashes must match. (JSON payloads are hashed in canonical form — recursively sorted keys, no whitespace — after deleting the two volatile envelope fields generated_at and integrity, which carry the build timestamp and the pinning entry's own hash and so cannot be inside the pinned content. /llms.txt is hashed as exact bytes, no jq step.) For the full guarantee, also confirm the mirror and origin ledgers agree and the signature chain verifies — that's steps 1–2 above, or npm run verify:ledger.

The boundary, honestly: a passing check proves the bytes that reached the edge of your process match Graviti's signed, Bitcoin-anchored record. Nothing cryptographic reaches inside your runtime or a model's context window after verification passes — if your own stack mutates the data afterwards, no publisher-side mechanism can see it. Verify as close to the point of use as you can; the last hop is yours.

Sync provenance

src/engine.ts, scripts/verify-ledger.mjs (modulo the live-fetch adaptation noted in its header), data/ledger.json, and data/public-key.pem mirror the private Graviti monorepo at commit cf24943 (2026-08-26). The engine file is verbatim — re-syncing is a file copy plus an update to this line, and it now happens automatically with every ledger snapshot sync. This sync carries the rubric-pinning release: from ledger v26 every entry's signed core carries a rubric field — the sha256 and git blob sha1 of the exact committed src/engine.ts that scored every ranking published under that entry, plus the pinning private-repo commit and this repository's URL. That makes the sync provenance checkable instead of stated:

# The engine in this repo must hash to exactly what the signed ledger head pins:
git hash-object src/engine.ts
curl -s https://graviti.thesingulariti.ai/ledger.json | jq -r '.entries[-1].rubric.engine_git_blob_sha1'
# — the two must match byte for byte. Equivalently, with no git:
sha256sum src/engine.ts   # must equal .entries[-1].rubric.engine_sha256

Read the full README on GitHub →