@reinconsole/graph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rein contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @reinconsole/graph
+
+Phase 3 of **[Rein](https://github.com/bugiiiii11/rein)** — the reputation graph. Guard receipts say what agents tried to spend; gate receipts say what vendors actually earned. The graph listens to both, scores every vendor and payer it has evidence on, and feeds the scores back into enforcement on both sides of the wire.
+
+> **Status: v0.1 — early open-source infrastructure, live on testnet.** APIs may change before 1.0. See the live scoreboard: [Rein console](https://reinconsole-production.up.railway.app/).
+
+## Install
+
+```bash
+npm install @reinconsole/graph
+```
+
+## Quickstart
+
+```ts
+import { ReputationGraph, payerCheck } from '@reinconsole/graph';
+
+const graph = new ReputationGraph().observe(engine).observe(indexer).observe(gate);
+
+// Agent side: pushed scores make `vendorReputationLt` policies fire.
+await graph.syncVendors(engine.spend);
+
+// Vendor side: confidently-bad wallets are turned away at the door.
+createGate({ screen: { check: payerCheck(graph, { denyBelow: 40 }) }, /* ... */ });
+```
+
+## How it scores
+
+- **Evidence, not vibes.** Per-subject history accumulates straight off the event buses — settlements, refusals (replays weighted heaviest), shadow spends, settled-money edges between counterparties, manual dispute/endorsement reports. Scores are **never stored**: they recompute from raw evidence on demand, so every score is explainable down to the counts behind it.
+- **Five components + confidence.** Settlement reliability, dispute hygiene, volume, longevity, and one-hop counterparty quality, blended 0–100. Confidence is first-class: thin or brand-new history yields low confidence, not a fake number — and same-day evidence is discounted until it ages.
+- **Unknown is not bad.** The evaluator never fires `vendorReputationLt` without data, `syncVendors` withholds scores under the confidence floor, and `payerCheck` passes wallets it knows nothing about. A newcomer is served; a *confidently* bad actor is refused.
+- **No-fault refusals carry no evidence.** Rate limits, velocity caps, and rails outages at one vendor's gate never bleed into a payer's global score.
+- **One identity, one history.** `graph.link(canonical, alias)` merges subjects across id spaces — an agent's engine ULID, its paying wallets, its on-chain [ERC-8004](https://www.npmjs.com/package/@reinconsole/erc8004) identity — so evidence follows the party, not the key. Key rotation never splits a score.
+- **Run it as a service.** `buildGraphServer()` — remote producers `POST /v1/events`, anyone reads `GET /v1/scores/:kind/:subject` and gets the score *and* the evidence behind it. The durable variant (evidence survives restarts) lives in the [monorepo](https://github.com/bugiiiii11/rein) (`@reinconsole/store`).
+
+Scoring weights are deliberately transparent v0.1 heuristics (`DEFAULT_WEIGHTS`, overridable) — scores are pure functions of the evidence ledger, so the model can evolve without migrations.
+
+MIT © Rein contributors · [Repository](https://github.com/bugiiiii11/rein) · [Issues](https://github.com/bugiiiii11/rein/issues)

package/dist/index.d.ts

@@ -0,0 +1,374 @@
+import { ReputationSubject, ReputationComponents, ReinEvent, ReputationScore, Receipt } from '@reinconsole/core';
+import { FastifyInstance } from 'fastify';
+
+/** A value that may be produced synchronously or awaited (durable writes). */
+type MaybePromise<T> = T | Promise<T>;
+/** One settled-money edge to a counterparty (the "graph" in reputation graph). */
+interface CounterpartyLine {
+    settled: number;
+    /** Settled decimal volume across this edge. */
+    volume: string;
+}
+/**
+ * Everything the graph has observed about one subject. Counters are raw and
+ * append-only — scoring (scoring.ts) is a pure function over this record, so a
+ * score is always re-derivable and explainable from the evidence behind it.
+ */
+interface SubjectEvidence {
+    subject: ReputationSubject;
+    firstSeenMs: number;
+    lastSeenMs: number;
+    /** Payment attempts observed (allowed intents, presented payments). */
+    attempts: number;
+    /** Confirmed settlements (indexer-reconciled or gate-receipted). */
+    settled: number;
+    /** Settled decimal volume. */
+    volume: string;
+    /** Refusals by code (gate refusal codes, signer refusal codes). */
+    refusals: Record<string, number>;
+    /** Managed-wallet spend with no ALLOW decision behind it (bypass). */
+    shadowSpends: number;
+    /** Manual out-of-band reports (chargebacks, fraud complaints). */
+    disputes: number;
+    /** Manual out-of-band vouches. */
+    endorsements: number;
+    /** Who this subject has settled money with, keyed by subjectKey(). */
+    counterparties: Map<string, CounterpartyLine>;
+}
+/**
+ * Canonical subject identity. Hosts and EVM addresses are case-insensitive,
+ * so they normalize to lowercase; ULID agent ids are case-sensitive and pass
+ * through. ERC-8004 ids (`eip155:{chainId}:{registry}/{tokenId}`) normalize
+ * via parse->format — @reinconsole/erc8004 always emits the canonical form, but this
+ * is the graph's OWN boundary (remote producers hit POST /v1/links with
+ * hand-built strings), and a checksummed registry or zero-padded tokenId
+ * variant must not mint a split subject row. Note the two id spaces under
+ * kind "agent": the engine names agents by ULID, a gate names them by paying
+ * wallet — ERC-8004 linking (S17) folds both into the on-chain identity.
+ */
+declare function normalizeSubject(subject: ReputationSubject): ReputationSubject;
+declare function subjectKey(subject: ReputationSubject): string;
+/**
+ * The evidence store seam the graph depends on. Writes may be asynchronous (a
+ * durable ledger persists behind them); reads are synchronous from the
+ * hydrated working set so `score()` / `payerCheck()` stay sync in the gate hot
+ * path. Mutations are explicit, atomic operations rather than a returned record
+ * the caller mutates — that is what lets a durable implementation persist them.
+ */
+interface EvidenceLedgerPort {
+    /** A payment attempt (allowed intent / presented payment). */
+    recordAttempt(subject: ReputationSubject, atMs: number): MaybePromise<void>;
+    /** A confirmed settlement between two subjects (credits both sides + the edge). */
+    recordSettlement(a: ReputationSubject, b: ReputationSubject, amount: string, atMs: number): MaybePromise<void>;
+    /** A refusal against a subject, by code. */
+    recordRefusal(subject: ReputationSubject, code: string, atMs: number): MaybePromise<void>;
+    /** Managed-wallet spend with no ALLOW behind it. */
+    recordShadowSpend(subject: ReputationSubject, atMs: number): MaybePromise<void>;
+    /** An out-of-band dispute. */
+    recordDispute(subject: ReputationSubject, atMs: number): MaybePromise<void>;
+    /** An out-of-band endorsement. */
+    recordEndorsement(subject: ReputationSubject, atMs: number): MaybePromise<void>;
+    /**
+     * Fold everything known about `alias` into `canonical` and forget the alias:
+     * counters sum, volumes add, first/last seen widen, and settled-money edges
+     * re-key on BOTH endpoints (peers that pointed at the alias now point at the
+     * canonical subject). No-op when the alias has no record — which makes
+     * re-asserting links at boot idempotent. This is the identity-linking
+     * primitive (ERC-8004: one on-chain identity, many addresses/ids).
+     */
+    merge(canonical: ReputationSubject, alias: ReputationSubject): MaybePromise<void>;
+    get(subject: ReputationSubject): SubjectEvidence | undefined;
+    getByKey(key: string): SubjectEvidence | undefined;
+    all(): IterableIterator<SubjectEvidence>;
+    readonly size: number;
+    /**
+     * Await any pending durable writes (no-op in memory). Durable
+     * implementations surface write failures HERE — the graph fire-and-forgets
+     * its writes (a bus handler cannot await), so flush() is the error channel.
+     */
+    flush?(): Promise<void>;
+}
+/** The evidence store: one record per subject, created on first sighting. */
+declare class EvidenceLedger implements EvidenceLedgerPort {
+    private readonly records;
+    recordAttempt(subject: ReputationSubject, atMs: number): void;
+    recordSettlement(a: ReputationSubject, b: ReputationSubject, amount: string, atMs: number): void;
+    recordRefusal(subject: ReputationSubject, code: string, atMs: number): void;
+    recordShadowSpend(subject: ReputationSubject, atMs: number): void;
+    recordDispute(subject: ReputationSubject, atMs: number): void;
+    recordEndorsement(subject: ReputationSubject, atMs: number): void;
+    merge(canonical: ReputationSubject, alias: ReputationSubject): void;
+    get(subject: ReputationSubject): SubjectEvidence | undefined;
+    getByKey(key: string): SubjectEvidence | undefined;
+    all(): IterableIterator<SubjectEvidence>;
+    get size(): number;
+    /**
+     * Insert a fully-formed record verbatim — the hydration primitive a durable
+     * store uses to rebuild the working set on open. Bypasses the live counters
+     * (the record already holds its accumulated state and timestamps).
+     */
+    load(record: SubjectEvidence): void;
+    /** Get-or-create the record for a subject and stamp first/last seen. */
+    private touch;
+}
+
+/**
+ * What an `intent.created` event tells us, kept until the matching
+ * `payment.settled` (which carries only an intentId) can be attributed.
+ */
+interface IntentFacts {
+    agentId: string;
+    host: string;
+    amount: string;
+}
+declare const DEFAULT_CORRELATION_LIMIT = 10000;
+/**
+ * Bridges `intent.created` -> later `payment.settled`/`decision.made`. A
+ * `payment.settled` event names only an intentId, so the graph remembers every
+ * undecided intent until it settles. Bounded (oldest-evicted) so undecided
+ * intents that never settle cannot leak. Writes may be async (a durable store
+ * persists them so an in-flight intent survives a restart); reads are sync.
+ */
+interface IntentCorrelationPort {
+    remember(intentId: string, facts: IntentFacts): MaybePromise<void>;
+    /** Read the facts without consuming them (decision.made reads, doesn't burn). */
+    peek(intentId: string): IntentFacts | undefined;
+    /** Read and consume (payment.settled attributes once, then forgets). */
+    take(intentId: string): IntentFacts | undefined;
+    readonly size: number;
+    /**
+     * Await any pending durable writes (no-op in memory). Durable
+     * implementations surface write failures HERE — the graph fire-and-forgets
+     * its writes, so flush() is the error channel.
+     */
+    flush?(): Promise<void>;
+}
+/** In-memory correlation map with FIFO eviction once `limit` is reached. */
+declare class InMemoryIntentStore implements IntentCorrelationPort {
+    private readonly limit;
+    private readonly intents;
+    constructor(limit?: number);
+    remember(intentId: string, facts: IntentFacts): void;
+    peek(intentId: string): IntentFacts | undefined;
+    take(intentId: string): IntentFacts | undefined;
+    get size(): number;
+}
+
+/**
+ * Component weights, summing to 1. The blend is a deliberately transparent
+ * heuristic: every component is 0–100 with higher = healthier, so a score is
+ * readable straight off its explanation. Sophistication can replace this
+ * later without touching the evidence model — scores are pure functions of
+ * evidence, never stored.
+ */
+interface ScoreWeights {
+    volume: number;
+    longevity: number;
+    disputeRate: number;
+    counterpartyQuality: number;
+    settlementReliability: number;
+}
+declare const DEFAULT_WEIGHTS: ScoreWeights;
+/** Saturating settled-transaction volume: 0 at none, ~63 at 20, ~92 at 50. */
+declare function volumeComponent(ev: SubjectEvidence): number;
+/** How long the subject has been known: linear to 100 at 30 days. */
+declare function longevityComponent(ev: SubjectEvidence, nowMs: number): number;
+/**
+ * Dispute hygiene (the core field is named `disputeRate`; the component is
+ * stored INVERTED — 100 = a clean record — so all five components blend in
+ * the same direction). Weighted badness over total interactions; manual
+ * endorsements buy back a little slack.
+ */
+declare function disputeComponent(ev: SubjectEvidence): number;
+/** Settled / attempted. No attempts yet = neutral 50, not perfect 100. */
+declare function reliabilityComponent(ev: SubjectEvidence): number;
+/**
+ * Confidence is first-class (see core ReputationScore): a thin or brand-new
+ * history yields LOW confidence rather than a misleading score, so consumers
+ * (engine sync, gate screening) can refuse to act on it. Depth of evidence
+ * saturates around 10 observations; age discounts same-day evidence to 40%
+ * and stops mattering after a week.
+ */
+declare function confidence(ev: SubjectEvidence, nowMs: number): number;
+/** Blend all five components into the headline 0–100 score. */
+declare function blend(components: ReputationComponents, weights: ScoreWeights): number;
+/**
+ * The one-hop base score: the blend WITHOUT counterpartyQuality, with the
+ * remaining weights renormalized. Counterparty quality for subject A averages
+ * the base scores of A's counterparties — base, not full, so the computation
+ * is a single hop and cycles (A pays B pays A) cannot recurse.
+ */
+declare function blendBase(ev: SubjectEvidence, nowMs: number, weights: ScoreWeights): number;
+
+/** Anything with a Rein event bus: engine, indexer, gate, signer. */
+interface EventSource {
+    onEvent(handler: (event: ReinEvent) => void): void;
+}
+/**
+ * Where vendor scores land. `PolicyEngine.spend` satisfies this structurally,
+ * so `graph.syncVendors(engine.spend)` closes the loop — durable when the
+ * engine runs on @reinconsole/store.
+ */
+interface VendorReputationSink {
+    setVendorReputation(host: string, score: number): void | Promise<void>;
+}
+interface ReputationGraphOptions {
+    weights?: Partial<ScoreWeights>;
+    /** Injectable clock (scores are functions of evidence AND time). */
+    now?: () => Date;
+    /**
+     * Max undecided intents remembered for settlement correlation. Ignored when
+     * a custom `intents` store is injected (that store owns its own bound).
+     */
+    correlationLimit?: number;
+    /**
+     * Durable evidence ledger. Defaults to in-memory; @reinconsole/store provides a
+     * PGlite-backed one so scores survive a restart.
+     */
+    ledger?: EvidenceLedgerPort;
+    /** Durable intent correlation store. Defaults to in-memory (bounded by `correlationLimit`). */
+    intents?: IntentCorrelationPort;
+}
+interface ManualReport {
+    subject: ReputationSubject;
+    kind: 'dispute' | 'endorsement';
+    /** When the incident happened (defaults to now). */
+    at?: Date;
+    note?: string;
+}
+interface SyncedVendorScore {
+    host: string;
+    score: number;
+    confidence: number;
+}
+interface SyncOptions {
+    /**
+     * Scores below this confidence are NOT pushed — the evaluator treats an
+     * unknown reputation as indeterminate (never triggers vendorReputationLt),
+     * and a thin history must stay unknown rather than condemn a newcomer.
+     */
+    minConfidence?: number;
+}
+/** A score plus the raw evidence it was derived from, render-ready. */
+interface ReputationExplanation {
+    score: ReputationScore;
+    weights: ScoreWeights;
+    evidence: {
+        attempts: number;
+        settled: number;
+        volume: string;
+        refusals: Record<string, number>;
+        shadowSpends: number;
+        disputes: number;
+        endorsements: number;
+        firstSeen: Date;
+        lastSeen: Date;
+        counterparties: {
+            subject: ReputationSubject;
+            settled: number;
+            volume: string;
+        }[];
+    };
+}
+/**
+ * The Rein reputation graph (Phase 3). Subscribes to the event buses both
+ * sides already publish — the engine/indexer name vendors by host and agents
+ * by id; a gate names payers by wallet — and accumulates per-subject evidence:
+ * settlements, refusals, shadow spends, manual disputes, and settled-money
+ * edges between counterparties. Scores are computed on demand (never stored)
+ * from that evidence, so every number is explainable, and they feed back into
+ * enforcement on both sides of the wire:
+ *
+ *   graph.syncVendors(engine.spend)  -> policies with vendorReputationLt fire
+ *   screen: { check: payerCheck(graph) } -> a gate turns away low-rep wallets
+ *
+ * Event mapping notes: engine-side evidence keys agents by ULID and vendors by
+ * host; gate-side evidence keys payers by wallet and recipients by payTo
+ * address — distinct subjects, so feeding one graph from BOTH buses (the
+ * console world) never double-counts. `payment.settled` carries only an
+ * intentId, so the graph keeps a bounded intent.created correlation map.
+ * Denied decisions are deliberately NOT held against anyone: a deny means
+ * policy worked, not that the agent or vendor misbehaved.
+ */
+declare class ReputationGraph {
+    private readonly ledger;
+    private readonly intents;
+    private readonly weights;
+    private readonly now;
+    /** aliasKey -> canonical subject. Links are derived state (an agent registry
+     * or ERC-8004 lookup knows them) — re-assert at boot; merges are idempotent. */
+    private readonly aliases;
+    constructor(options?: ReputationGraphOptions);
+    /** Subscribe to a bus. Returns `this` so construction chains. */
+    observe(source: EventSource): this;
+    /**
+     * Fire-and-forget a port write: bus handlers cannot await, and a rejecting
+     * durable write must never become an unhandled rejection (Node kills the
+     * process). Failures are the port's to surface — flush() throws them.
+     */
+    private fire;
+    /**
+     * Declare that `alias` is the same real-world party as `canonical` (the
+     * ERC-8004 identity story: one identity, many addresses/ids — an engine
+     * agent's ULID and its paying wallet, or a vendor's host and its payTo
+     * address). Everything already known about the alias is folded into the
+     * canonical subject, and all future evidence and lookups for the alias
+     * resolve to it. Idempotent — re-asserting known links at boot is free.
+     */
+    link(canonical: ReputationSubject, alias: ReputationSubject): void;
+    /** The canonical subject for a possibly-aliased one. */
+    private resolve;
+    ingest(event: ReinEvent): void;
+    /**
+     * Agent-side alternative to observing the engine bus: feed the SDK guard's
+     * onReceipt straight in. Connect events OR receipts per side, not both —
+     * a receipt restates the decision/settlement the bus already carried.
+     */
+    ingestReceipt(receipt: Receipt): void;
+    /** Record an out-of-band dispute or endorsement against a subject. */
+    report(input: ManualReport): void;
+    /** Await any pending durable writes (no-op for in-memory stores). */
+    flush(): Promise<void>;
+    /** The score for one subject, or undefined when nothing is known (fairness).
+     *  Aliased subjects resolve to their canonical identity — a linked wallet
+     *  answers with the merged history, on both sides of the wire. */
+    score(subject: ReputationSubject): ReputationScore | undefined;
+    /** All known scores, best first. */
+    scores(kind?: ReputationSubject['kind']): ReputationScore[];
+    /** The score plus the raw evidence behind it. */
+    explain(subject: ReputationSubject): ReputationExplanation | undefined;
+    /**
+     * Push every vendor score that clears the confidence floor into the engine's
+     * spend store (or any sink). Returns what was pushed. Low-confidence scores
+     * are withheld so `vendorReputationLt` keeps treating thin histories as
+     * unknown — the evaluator's no-data-no-trigger rule stays intact end to end.
+     */
+    syncVendors(sink: VendorReputationSink, options?: SyncOptions): Promise<SyncedVendorScore[]>;
+    /** Number of subjects with evidence. */
+    subjects(): number;
+    private scoreOf;
+    /** One-hop mean of the counterparties' base scores; neutral 50 when alone. */
+    private counterpartyQuality;
+}
+interface PayerCheckOptions {
+    /** Refuse payers scoring below this (default 40). */
+    denyBelow?: number;
+    /** Ignore scores below this confidence (default 0.3) — newcomers pass. */
+    minConfidence?: number;
+}
+/**
+ * Reputation-driven gate screening: plugs into @reinconsole/gate's `screen.check`.
+ * Unknown wallets and thin histories pass (same fairness rule as the engine
+ * sync); a confident low score is turned away at the door, before any
+ * facilitator round-trip.
+ */
+declare function payerCheck(graph: ReputationGraph, options?: PayerCheckOptions): (payer: string) => string | undefined;
+
+/**
+ * Build the graph HTTP API. Remote producers POST their events here; anyone
+ * can read scores with the evidence behind them. Pass a graph for tests, or
+ * let it create a fresh in-memory one.
+ */
+declare function buildGraphServer(graph?: ReputationGraph): FastifyInstance;
+
+export { type CounterpartyLine, DEFAULT_CORRELATION_LIMIT, DEFAULT_WEIGHTS, type EventSource, EvidenceLedger, type EvidenceLedgerPort, InMemoryIntentStore, type IntentCorrelationPort, type IntentFacts, type ManualReport, type MaybePromise, type PayerCheckOptions, type ReputationExplanation, ReputationGraph, type ReputationGraphOptions, type ScoreWeights, type SubjectEvidence, type SyncOptions, type SyncedVendorScore, type VendorReputationSink, blend, blendBase, buildGraphServer, confidence, disputeComponent, longevityComponent, normalizeSubject, payerCheck, reliabilityComponent, subjectKey, volumeComponent };