@juspay/neurolink/dist/proxy/shareAudit.d.ts

The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002

/**
 * Trust-but-verify for complete-mode shares.
 *
 * A complete-mode borrower calls the provider directly, so the lender never sees
 * its requests and its reported spend is, strictly, an assertion. This module is
 * what stops that assertion from being the only evidence.
 *
 * **The signal.** The provider reports the account's own utilization, and the
 * borrower cannot influence that number. If an account's window moved between
 * two heartbeats, someone spent it. If the lender's own node served nothing on
 * that account in the same interval, and the borrower reported nothing either,
 * then something consumed the account that neither party is accounting for —
 * which is exactly the shape of a borrower that stopped reporting.
 *
 * **Why it is conservative.** The check only fires when the lender's own traffic
 * on that account was zero for the interval. A busy lender moves the same
 * numbers, and a false accusation is worse than a missed one: the remedy here is
 * to pause someone's access. Everything ambiguous is reported as `attributable`
 * and left alone.
 *
 * This detects a borrower that under-reports. It does not, and cannot, detect
 * one that reports honestly and simply spends what it was lent. It is also blind
 * across a window reset: utilization that falls between two check-ins reads as
 * no movement, so spend timed around a rollover goes unremarked. Closing that
 * would mean trusting a reset timestamp the borrower also influences, which is
 * a worse trade than the gap.
 *
 * @module proxy/shareAudit
 */
import type { ProxyShareAuditObservation, ProxyShareAuditRecord, ProxyShareDriftVerdict } from "../types/index.js";
/**
 * How much of a window may move unexplained before it counts as drift.
 *
 * Utilization is reported coarsely and can tick from rounding or from a request
 * that was in flight across the boundary, so a hair-trigger would cry wolf.
 */
export declare const DRIFT_TOLERANCE_PCT = 2;
/** Consecutive drifting heartbeats tolerated before the grant is paused. */
export declare const DRIFT_STREAK_LIMIT = 3;
export declare function initShareAudit(auditFilePath: string): void;
/**
 * Compare one heartbeat against the account's real movement.
 *
 * Pure: the caller supplies the previous observation and the current one, so the
 * decision is inspectable and testable without any I/O.
 */
export declare function evaluateDrift(previous: ProxyShareAuditObservation | undefined, current: ProxyShareAuditObservation, tolerancePct?: number): ProxyShareDriftVerdict;
export declare function getAuditRecord(grantId: string): Promise<ProxyShareAuditRecord | undefined>;
export declare function listAuditRecords(): Promise<ProxyShareAuditRecord[]>;
/**
 * Fold a heartbeat into the audit trail.
 *
 * Returns whether the grant has now drifted past tolerance often enough to be
 * paused — the caller owns that decision, because pausing is a policy action and
 * this module only supplies evidence.
 */
export declare function recordAuditObservation(args: {
    grantId: string;
    accountLabel: string;
    observation: ProxyShareAuditObservation;
    /** Lifetime lender-served request count, differenced against the stored
     *  total to yield this interval's `lenderRequests`. */
    lenderRequestsTotal?: number;
    streakLimit?: number;
    tolerancePct?: number;
}): Promise<{
    verdict: ProxyShareDriftVerdict;
    shouldPause: boolean;
}>;
/**
 * Clear a grant's drift streak and its auto-pause marker.
 *
 * Called when the lender resumes a grant. Without it the marker is permanent
 * and `shouldPause` can never fire again, so a grant auto-paused once would
 * drift freely for the rest of its life. The observation baseline is kept: it
 * is the account's real utilization and is still the right thing to difference
 * the next heartbeat against.
 */
export declare function clearAuditDrift(grantId: string): Promise<void>;
/** Forget a grant's audit trail — used when the grant itself is deleted. */
export declare function clearAuditRecord(grantId: string): Promise<void>;