@juspay/neurolink 11.29.2 → 11.30.0

package/dist/proxy/proxyPaths.d.ts

@@ -15,3 +15,11 @@
 import type { ProxyPaths } from "../types/index.js";
 export declare function resolveProxyPaths(dev: boolean): ProxyPaths;
 export declare function resolveProxyUsageStatsPath(paths: ProxyPaths): string;
+export declare function resolveProxyGrantsPath(paths: ProxyPaths): string;
+export declare function resolveProxyLedgerPath(paths: ProxyPaths): string;
+export declare function resolveProxyPeersPath(paths: ProxyPaths): string;
+export declare function resolveProxyResidentGrantsPath(paths: ProxyPaths): string;
+export declare function resolveProxyShareAuditPath(paths: ProxyPaths): string;
+export declare function resolveProxyProvisioningPath(paths: ProxyPaths): string;
+export declare function resolveProxyReceiptsPath(paths: ProxyPaths): string;
+export declare function resolveProxyNotesPath(paths: ProxyPaths): string;

package/dist/proxy/proxyPaths.js

@@ -14,28 +14,66 @@
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
+/**
+ * The state files, named once.
+ *
+ * Each name used to appear three times — dev branch, home branch, and the
+ * resolver's fallback — which is three places to keep in step and two chances
+ * to write a dev proxy's state into the global directory.
+ */
+const FILE_NAMES = {
+    quota: "account-quotas.json",
+    cooldown: "account-cooldowns.json",
+    stats: "proxy-usage-stats.json",
+    grants: "proxy-grants.json",
+    ledger: "proxy-share-ledger.json",
+    peers: "proxy-peers.json",
+    residentGrants: "proxy-resident-grants.json",
+    shareAudit: "proxy-share-audit.json",
+    provisioning: "proxy-share-provisioning.json",
+    receipts: "proxy-share-receipts.json",
+    notes: "proxy-share-notes.json",
+};
 export function resolveProxyPaths(dev) {
-    if (dev) {
-        const base = join(process.cwd(), ".neurolink-dev");
-        return {
-            stateDir: base,
-            logsDir: join(base, "logs"),
-            quotaFile: join(base, "account-quotas.json"),
-            cooldownFile: join(base, "account-cooldowns.json"),
-            statsFile: join(base, "proxy-usage-stats.json"),
-            isDev: true,
-        };
-    }
-    const base = join(homedir(), ".neurolink");
+    const base = dev
+        ? join(process.cwd(), ".neurolink-dev")
+        : join(homedir(), ".neurolink");
     return {
         stateDir: base,
         logsDir: join(base, "logs"),
-        quotaFile: join(base, "account-quotas.json"),
-        cooldownFile: join(base, "account-cooldowns.json"),
-        statsFile: join(base, "proxy-usage-stats.json"),
-        isDev: false,
+        quotaFile: join(base, FILE_NAMES.quota),
+        cooldownFile: join(base, FILE_NAMES.cooldown),
+        statsFile: join(base, FILE_NAMES.stats),
+        grantsFile: join(base, FILE_NAMES.grants),
+        ledgerFile: join(base, FILE_NAMES.ledger),
+        peersFile: join(base, FILE_NAMES.peers),
+        isDev: dev,
     };
 }
 export function resolveProxyUsageStatsPath(paths) {
-    return paths.statsFile ?? join(paths.stateDir, "proxy-usage-stats.json");
+    return paths.statsFile ?? join(paths.stateDir, FILE_NAMES.stats);
+}
+export function resolveProxyGrantsPath(paths) {
+    return paths.grantsFile ?? join(paths.stateDir, FILE_NAMES.grants);
+}
+export function resolveProxyLedgerPath(paths) {
+    return paths.ledgerFile ?? join(paths.stateDir, FILE_NAMES.ledger);
+}
+export function resolveProxyPeersPath(paths) {
+    return paths.peersFile ?? join(paths.stateDir, FILE_NAMES.peers);
+}
+export function resolveProxyResidentGrantsPath(paths) {
+    return join(paths.stateDir, FILE_NAMES.residentGrants);
+}
+export function resolveProxyShareAuditPath(paths) {
+    return join(paths.stateDir, FILE_NAMES.shareAudit);
+}
+export function resolveProxyProvisioningPath(paths) {
+    return join(paths.stateDir, FILE_NAMES.provisioning);
+}
+export function resolveProxyReceiptsPath(paths) {
+    return join(paths.stateDir, FILE_NAMES.receipts);
+}
+export function resolveProxyNotesPath(paths) {
+    return join(paths.stateDir, FILE_NAMES.notes);
 }

package/dist/proxy/requestLogger.js

@@ -13,6 +13,7 @@ import { writeFile } from "fs/promises";
 import { createHash } from "crypto";
 import { promisify } from "util";
 import { gzip as gzipCallback } from "zlib";
+import { isBorrowedRequest } from "./shareContext.js";
 import { OtelBridge } from "../observability/otelBridge.js";
 import { SeverityNumber } from "@opentelemetry/api-logs";
 import { configureProxyLifecycleLogger } from "./proxyLifecycle.js";
@@ -558,6 +559,13 @@ export async function logBodyCapture(entry) {
     if (!logEnabled || !logDir) {
         return;
     }
+    // Borrowed traffic is somebody else's conversation. Capturing it would leave
+    // a peer's prompts and the model's replies on this machine's disk, which is
+    // not something a share token can be read as consenting to. The request is
+    // still logged; only the bodies are dropped.
+    if (isBorrowedRequest()) {
+        return;
+    }
     const bridge = new OtelBridge();
     const traceCtx = entry.traceId && entry.spanId
         ? { traceId: entry.traceId, spanId: entry.spanId }

package/dist/proxy/residentGrants.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Credentials a lender provisioned onto this device, and the leases that keep
+ * them legitimate.
+ *
+ * This is the borrower's half of **complete** sharing. The credential itself
+ * lives in the normal token store and is routed like any other account — that is
+ * the point, since it survives the lender being offline. What lives here is the
+ * proof that the lender still consents, and the machinery to keep it fresh.
+ *
+ * **The enforcement is cooperative and the code should say so.** A resident
+ * credential sits on a machine its holder controls, and the token store is
+ * obfuscated rather than encrypted. Someone determined to bypass this can. What
+ * these checks buy is that the honest path is also the correct one: a borrower
+ * running the shipped software stops when the lender says stop, and stops on its
+ * own if the lender becomes unreachable for longer than the lease allows.
+ *
+ * @module proxy/residentGrants
+ */
+import type { ProxyResidentGrant, ProxyShareLease, ProxyShareLeaseVerdict } from "../types/index.js";
+export declare function initResidentGrants(filePath: string): void;
+export declare function listResidentGrants(): Promise<ProxyResidentGrant[]>;
+export declare function getResidentGrantForAccount(accountKeyOrLabel: string): Promise<ProxyResidentGrant | undefined>;
+export declare function saveResidentGrant(grant: ProxyResidentGrant): Promise<void>;
+export declare function removeResidentGrant(accountLabel: string): Promise<boolean>;
+/**
+ * May this resident account serve right now?
+ *
+ * Returns `undefined` for an account that is not resident at all — the node's
+ * own credentials, which answer to nobody.
+ */
+export declare function evaluateResidentAccount(accountKeyOrLabel: string, now?: number): Promise<ProxyShareLeaseVerdict | undefined>;
+/** Accumulate spend the borrower owes the lender an account of. */
+export declare function recordResidentSpend(accountLabel: string, coins: number): Promise<void>;
+/**
+ * Check in with a lender: report what was spent, collect a fresh lease.
+ *
+ * Reporting happens **before** the new lease is stored, and the counters are
+ * only drawn down once the lender has acknowledged them — a heartbeat that
+ * fails halfway leaves the spend to be reported again rather than losing it.
+ *
+ * A `stop` answer is honored immediately by clearing the lease's grace: the
+ * lender has said no, and there is nothing to wait out.
+ */
+export declare function heartbeatResidentGrant(resident: ProxyResidentGrant, now?: number): Promise<{
+    ok: boolean;
+    stopped: boolean;
+    detail: string;
+}>;
+/**
+ * Check in with every lender whose heartbeat is due.
+ *
+ * Best-effort by design: a lender being unreachable is the case the offline
+ * grace exists for, not an error to surface.
+ */
+export declare function heartbeatDueResidentGrants(now?: number): Promise<void>;
+/** The lease a resident account is currently operating under. */
+export declare function residentLease(resident: ProxyResidentGrant): ProxyShareLease;

package/dist/proxy/residentGrants.js

@@ -0,0 +1,393 @@
+/**
+ * Credentials a lender provisioned onto this device, and the leases that keep
+ * them legitimate.
+ *
+ * This is the borrower's half of **complete** sharing. The credential itself
+ * lives in the normal token store and is routed like any other account — that is
+ * the point, since it survives the lender being offline. What lives here is the
+ * proof that the lender still consents, and the machinery to keep it fresh.
+ *
+ * **The enforcement is cooperative and the code should say so.** A resident
+ * credential sits on a machine its holder controls, and the token store is
+ * obfuscated rather than encrypted. Someone determined to bypass this can. What
+ * these checks buy is that the honest path is also the correct one: a borrower
+ * running the shipped software stops when the lender says stop, and stops on its
+ * own if the lender becomes unreachable for longer than the lease allows.
+ *
+ * @module proxy/residentGrants
+ */
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { AsyncMutex } from "../utils/asyncMutex.js";
+import { logger } from "../utils/logger.js";
+import { evaluateLease, isHeartbeatDue, isLeaseAuthentic, } from "./shareLease.js";
+import { writeJsonSnapshotAtomically } from "./snapshotPersistence.js";
+const RESIDENT_FILE = "proxy-resident-grants.json";
+const HEARTBEAT_TIMEOUT_MS = 10_000;
+/**
+ * How long a read may trust the cache before it stats the file again.
+ *
+ * The CLI writes this file from a separate process — `share accept`, `peer
+ * provision`, a manual removal — so a load-once cache would let a long-lived
+ * proxy keep serving from a grant the operator revoked minutes ago.
+ */
+const RELOAD_TTL_MS = 1_000;
+let customFilePath = null;
+let cache = {};
+let cacheLoadedAt = 0;
+let cacheMtimeMs = -1;
+let cacheValid = false;
+const mutationMutex = new AsyncMutex();
+export function initResidentGrants(filePath) {
+    customFilePath = filePath;
+    cache = {};
+    cacheLoadedAt = 0;
+    cacheMtimeMs = -1;
+    cacheValid = false;
+}
+function getFilePath() {
+    return customFilePath ?? join(homedir(), ".neurolink", RESIDENT_FILE);
+}
+function isResidentGrant(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.accountLabel === "string" &&
+        typeof candidate.grantId === "string" &&
+        typeof candidate.leaseSecret === "string" &&
+        !!candidate.lease);
+}
+/**
+ * Is this error simply "the file is not there yet"?
+ *
+ * The distinction is load-bearing. An absent file genuinely is an empty map —
+ * nothing has been written yet. Every *other* `stat`/read failure (`EACCES`,
+ * `EIO`, `EMFILE`, a full descriptor table) is a failure to observe the file,
+ * and answering one with an empty map is how a whole store gets erased: a
+ * caller passing `force` is about to `persist()` the map back over the real
+ * contents it just failed to read.
+ */
+function isMissingFileError(error) {
+    return error?.code === "ENOENT";
+}
+async function ensureLoaded(options = {}) {
+    const now = Date.now();
+    if (!options.force && cacheValid && now - cacheLoadedAt < RELOAD_TTL_MS) {
+        return;
+    }
+    const path = getFilePath();
+    let mtimeMs;
+    try {
+        mtimeMs = (await stat(path)).mtimeMs;
+    }
+    catch (error) {
+        if (!isMissingFileError(error)) {
+            // Not "no file" but "could not look" — see `isMissingFileError`. Let it
+            // out: a mutation must abort rather than persist an empty map over a
+            // store it never managed to read.
+            throw error;
+        }
+        cache = {};
+        cacheMtimeMs = -1;
+        cacheLoadedAt = now;
+        cacheValid = true;
+        return;
+    }
+    // A forced load skips this. mtime is the fast path for a read, not a
+    // correctness check for a write: several filesystems stamp it at one-second
+    // granularity, so a write landing in the same second as our last read is
+    // indistinguishable from no write at all — and every caller passing `force`
+    // is about to persist the whole map back over whatever it missed.
+    if (!options.force && cacheValid && mtimeMs === cacheMtimeMs) {
+        cacheLoadedAt = now;
+        return;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        cache = Object.fromEntries(Object.entries(parsed?.grants ?? {}).filter((entry) => isResidentGrant(entry[1])));
+    }
+    catch (error) {
+        if (options.force) {
+            // A mutation is about to write the whole map back; treating a corrupt
+            // file as empty here would make that write finish the corruption off.
+            // Abort instead and leave the file for a human. Reads stay tolerant.
+            throw error;
+        }
+        cache = {};
+    }
+    cacheMtimeMs = mtimeMs;
+    cacheLoadedAt = now;
+    cacheValid = true;
+}
+async function persist() {
+    const file = { schemaVersion: 1, grants: cache };
+    await writeJsonSnapshotAtomically(getFilePath(), file);
+    try {
+        cacheMtimeMs = (await stat(getFilePath())).mtimeMs;
+    }
+    catch {
+        cacheMtimeMs = -1;
+    }
+    cacheLoadedAt = Date.now();
+    cacheValid = true;
+}
+/**
+ * Narrow a heartbeat answer to its stopping half.
+ * Explicit because one build step compiles without `strictNullChecks`, where a
+ * boolean discriminant does not narrow.
+ */
+function isHeartbeatStop(payload) {
+    return !payload.ok;
+}
+/**
+ * Is this shaped like a lease at all?
+ *
+ * Shape only — {@link isLeaseAuthentic} decides whether it is *ours*. Both run
+ * before a renewal is allowed to replace a lease that currently works, because
+ * the answer comes off the wire and an `{ ok: true }` with no usable lease
+ * would otherwise be persisted over the one keeping this account alive.
+ */
+function isShareLease(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.grantId === "string" &&
+        typeof candidate.signature === "string" &&
+        typeof candidate.issuedAt === "number" &&
+        typeof candidate.notAfter === "number" &&
+        typeof candidate.heartbeatEveryMs === "number" &&
+        typeof candidate.offlineGraceMs === "number" &&
+        !!candidate.gates);
+}
+/** The matching predicate for the renewing half. */
+function isHeartbeatRenewal(payload) {
+    return payload.ok === true && isShareLease(payload.lease);
+}
+/** Key by the account label, since that is how the routing path addresses it. */
+function keyFor(accountLabel) {
+    return accountLabel.toLowerCase();
+}
+export async function listResidentGrants() {
+    await ensureLoaded();
+    return Object.values(cache);
+}
+export async function getResidentGrantForAccount(accountKeyOrLabel) {
+    await ensureLoaded();
+    const value = accountKeyOrLabel.toLowerCase();
+    const label = value.includes(":")
+        ? value.slice(value.indexOf(":") + 1)
+        : value;
+    return cache[keyFor(label)];
+}
+export async function saveResidentGrant(grant) {
+    await mutationMutex.runExclusive(async () => {
+        // Force: `persist()` writes the whole map back, so a mutation that ran on a
+        // TTL-fresh snapshot would resurrect a grant the CLI removed in the window
+        // since this process last read the file.
+        await ensureLoaded({ force: true });
+        cache[keyFor(grant.accountLabel)] = grant;
+        await persist();
+    });
+}
+export async function removeResidentGrant(accountLabel) {
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const key = keyFor(accountLabel);
+        if (!cache[key]) {
+            return false;
+        }
+        delete cache[key];
+        await persist();
+        return true;
+    });
+}
+/**
+ * May this resident account serve right now?
+ *
+ * Returns `undefined` for an account that is not resident at all — the node's
+ * own credentials, which answer to nobody.
+ */
+export async function evaluateResidentAccount(accountKeyOrLabel, now = Date.now()) {
+    const resident = await getResidentGrantForAccount(accountKeyOrLabel);
+    if (!resident) {
+        return undefined;
+    }
+    return evaluateLease({
+        lease: resident.lease,
+        secret: resident.leaseSecret,
+        ...(resident.lastHeartbeatAt !== undefined
+            ? { lastHeartbeatAt: resident.lastHeartbeatAt }
+            : {}),
+        now,
+    });
+}
+/** Accumulate spend the borrower owes the lender an account of. */
+export async function recordResidentSpend(accountLabel, coins) {
+    await mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const key = keyFor(accountLabel);
+        const resident = cache[key];
+        if (!resident) {
+            return;
+        }
+        cache[key] = {
+            ...resident,
+            unreportedCoins: (resident.unreportedCoins ?? 0) + coins,
+            unreportedRequests: (resident.unreportedRequests ?? 0) + 1,
+        };
+        await persist();
+    });
+}
+/**
+ * Apply a heartbeat's outcome to whatever the record says **now**.
+ *
+ * The round trip takes up to {@link HEARTBEAT_TIMEOUT_MS} and requests keep
+ * being served throughout it, so writing back the snapshot the heartbeat
+ * started from would silently drop every coin {@link recordResidentSpend}
+ * booked in that window. The reported amounts are subtracted from the current
+ * counters instead of the counters being zeroed, and the record is re-read
+ * rather than reconstructed from the caller's copy.
+ */
+async function settleHeartbeat(args) {
+    await mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const key = keyFor(args.accountLabel);
+        const current = cache[key];
+        if (!current) {
+            return;
+        }
+        cache[key] = {
+            ...current,
+            lease: args.outcome === "stop"
+                ? // Force the next evaluation to fail closed without waiting out grace.
+                    { ...current.lease, notAfter: args.now }
+                : args.outcome.lease,
+            lastHeartbeatAt: args.now,
+            unreportedCoins: Math.max(0, (current.unreportedCoins ?? 0) - args.reportedCoins),
+            unreportedRequests: Math.max(0, (current.unreportedRequests ?? 0) - args.reportedRequests),
+        };
+        await persist();
+    });
+}
+/**
+ * Check in with a lender: report what was spent, collect a fresh lease.
+ *
+ * Reporting happens **before** the new lease is stored, and the counters are
+ * only drawn down once the lender has acknowledged them — a heartbeat that
+ * fails halfway leaves the spend to be reported again rather than losing it.
+ *
+ * A `stop` answer is honored immediately by clearing the lease's grace: the
+ * lender has said no, and there is nothing to wait out.
+ */
+export async function heartbeatResidentGrant(resident, now = Date.now()) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), HEARTBEAT_TIMEOUT_MS);
+    // Exactly what this round trip claims to have reported, so the settle can
+    // subtract that and nothing more.
+    const reportedCoins = resident.unreportedCoins ?? 0;
+    const reportedRequests = resident.unreportedRequests ?? 0;
+    try {
+        const response = await fetch(`${resident.lenderUrl}/peer/heartbeat`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-neurolink-share-token": resident.leaseSecret,
+                "x-neurolink-grant-id": resident.grantId,
+            },
+            body: JSON.stringify({
+                grantId: resident.grantId,
+                coinsSpent: reportedCoins,
+                requests: reportedRequests,
+                reportedAt: now,
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                stopped: false,
+                detail: `lender answered ${response.status}`,
+            };
+        }
+        const payload = (await response.json());
+        if (isHeartbeatStop(payload)) {
+            await settleHeartbeat({
+                accountLabel: resident.accountLabel,
+                reportedCoins,
+                reportedRequests,
+                outcome: "stop",
+                now,
+            });
+            logger.always(`[proxy] lender stopped resident grant ${resident.accountLabel}: ${payload.reason}`);
+            return { ok: true, stopped: true, detail: payload.reason };
+        }
+        if (!isHeartbeatRenewal(payload)) {
+            return {
+                ok: false,
+                stopped: false,
+                detail: "lender answered with neither a lease nor a stop",
+            };
+        }
+        // A renewal that is not signed by the secret we already hold, or that is
+        // for some other grant, is not a renewal — keep the working lease and let
+        // the offline grace run. Replacing it would hand any party that can answer
+        // this request the ability to revoke us, or to extend us indefinitely.
+        if (payload.lease.grantId !== resident.grantId) {
+            return {
+                ok: false,
+                stopped: false,
+                detail: "renewed lease is for a different grant",
+            };
+        }
+        if (!isLeaseAuthentic(payload.lease, resident.leaseSecret)) {
+            return {
+                ok: false,
+                stopped: false,
+                detail: "renewed lease is not signed by the lender's secret",
+            };
+        }
+        await settleHeartbeat({
+            accountLabel: resident.accountLabel,
+            reportedCoins,
+            reportedRequests,
+            outcome: { lease: payload.lease },
+            now,
+        });
+        return { ok: true, stopped: false, detail: "lease renewed" };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stopped: false,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Check in with every lender whose heartbeat is due.
+ *
+ * Best-effort by design: a lender being unreachable is the case the offline
+ * grace exists for, not an error to surface.
+ */
+export async function heartbeatDueResidentGrants(now = Date.now()) {
+    const grants = await listResidentGrants();
+    for (const resident of grants) {
+        if (!isHeartbeatDue(resident.lease, resident.lastHeartbeatAt, now)) {
+            continue;
+        }
+        const result = await heartbeatResidentGrant(resident, now);
+        if (!result.ok) {
+            logger.debug(`[proxy] heartbeat to ${resident.lenderName} failed: ${result.detail}`);
+        }
+    }
+}
+/** The lease a resident account is currently operating under. */
+export function residentLease(resident) {
+    return resident.lease;
+}

package/dist/proxy/shareAudit.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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>;