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
- 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.
- 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:
- 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 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.
Run the canaries
Graviti runs canary-based drift detection: subjects of known ground truth are pushed through the system on every production build (Panel A — golden routing queries, structural invariants like no NaN score anywhere and catalog-tier brands never rank, and adversarial cases where the famous answer must NOT win) and through the audit crawler on every cycle (Panel B — three provenance pages the site controls: one steady, one deliberately drifted, one deliberately gone). A Panel A divergence fails the build; a Panel B misread means the sensor itself is broken and that crawl cycle refreshes no real claims. The two panels are independently maintained so neither becomes the other's ground truth.
scripts/canary-panel-a.ts is the public subset of Panel A — the cases the sample index supports, over the exact engine this repository publishes, so you can run the same canaries the build runs with zero secrets. Live status for both panels is published in the canaries block of pulse.json (human-readable at /pulse).
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
npm run verify:ledger -- --live
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
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:
- 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);
- 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;
- recomputes the sha256 of the payload you actually received and compares it to the head entry's signed manifest;
- 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.
Verify Graviti traffic — outbound attribution (for brands)
Every recommendation link Graviti produces to a brand's own site carries deterministic UTMs (utm_source=graviti, utm_medium=<surface: agent|console|scan|landscape|report>, utm_campaign=<category>, utm_content=<brand>) plus a signed gvt token, so the brand on the receiving end can prove the referral came from Graviti instead of trusting a spoofable UTM string. The token (gvt1.<surface>.<category>.<brand>.<YYYYMMDD>.<sig>) is Ed25519-signed with the same key that signs the ledger, and identifies the recommendation surface, never the user — no user identifiers, no click IDs, no per-click values. Full spec: docs/ATTRIBUTION.md.
node scripts/verify-attribution.mjs 'gvt1.agent.magnesium-supplements.bioptimizers.20260829.<sig>'
Dependency-free (Node ≥ 20), pinned key, exit 0 only on a valid signature. The equivalent openssl commands are in the spec.
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:
git hash-object src/engine.ts
curl -s https://graviti.thesingulariti.ai/ledger.json | jq -r '.entries[-1].rubric.engine_git_blob_sha1'
sha256sum src/engine.ts
The blob hash is computed by git hash-object over the raw committed file bytes (no normalization), so any checkout of this mirror — or of the private repo at the pinned commit — reproduces it. A scoring change is therefore a public, diffable event: the ledger entry that ships it pins the new hash, and this file's history shows the diff. If this repo's engine ever fails that check, the mirror is out of sync (or you're comparing against a ledger newer than your checkout) — npm run verify:ledger performs the same cross-check and says which. This release also ships the claim-decay classes: the per-claim freshness policy (CLAIM_DECAY_CLASSES / CLAIM_DECAY_RULES in the engine — fast 45d, medium 120d, slow 365d, static) under which a claim past its disclosed window is marked "stale — pending re-verification" on every payload and counts at half weight where claim depth feeds scoring — visibly degraded, never zeroed, because stale is not false.
Layout
src/engine.ts the engine — types, laws, scoring, disclosure (verbatim production module)
data/sample-index.json real slice of the public index so the demo runs offline
data/ledger.json committed snapshot of the public integrity ledger
data/public-key.pem Ed25519 public key the ledger signatures verify against
demo/run.ts CLI demo — question in, ranked disclosure-carrying answer out
scripts/verify-ledger.mjs no-secrets ledger verification (chain, signatures, live index hash)
scripts/verify-payload.mjs client-side transport-integrity check — pinned key, two ledger paths, replay guard
src/attribution.ts shared outbound-attribution module (UTM scheme, gvt token format, pinned key)
scripts/verify-attribution.mjs brand-side gvt token verifier — prove a referral came from Graviti
docs/ATTRIBUTION.md the attribution spec: scheme, token format, signing model, privacy stance
License
Apache-2.0 — Copyright 2026 Singulariti.