usertrust 0.1.0

package/dist/ledger/engine.js

@@ -0,0 +1,142 @@
+/**
+ * Two-phase spend engine for the usertrust SDK.
+ * Implements PENDING -> POST/VOID lifecycle for all governed operations.
+ *
+ * Extracted from usertools platform TokenEngineImpl.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CreateTransferError } from "tigerbeetle-node";
+import { DEFAULT_HOLD_TTL_MS } from "../shared/constants.js";
+import { InsufficientBalanceError } from "../shared/errors.js";
+import { fnv1a32 } from "../shared/ids.js";
+import { XFER_SPEND } from "./client.js";
+import { estimateCost } from "./pricing.js";
+function writeDeadLetter(entry, dlqPath) {
+    try {
+        if (!existsSync(dlqPath)) {
+            mkdirSync(dlqPath, { recursive: true });
+        }
+        const line = `${JSON.stringify(entry)}\n`;
+        const filePath = join(dlqPath, "dead-letter.jsonl");
+        writeFileSync(filePath, line, { flag: "a" });
+    }
+    catch (err) {
+        console.error("[usertrust] Failed to write dead letter:", err);
+    }
+}
+// ── Helpers ──
+/** Derive a 64-bit user fingerprint for user_data_64 on transfers. */
+function deriveUserId64(userId) {
+    const hash = createHash("sha256").update(userId).digest("hex");
+    return BigInt(`0x${hash.slice(0, 16)}`);
+}
+/** Check whether a caught error is a TigerBeetle insufficient-balance rejection. */
+function isInsufficientBalanceError(err) {
+    if (err == null || typeof err !== "object")
+        return false;
+    if (!("code" in err) || !("name" in err))
+        return false;
+    const e = err;
+    return (e.name === "TBTransferError" &&
+        (e.code === CreateTransferError.exceeds_credits ||
+            e.code === CreateTransferError.overflows_debits ||
+            e.code === CreateTransferError.overflows_debits_pending));
+}
+// ── Engine ──
+export class TrustEngine {
+    tb;
+    holdTtlMs;
+    dlqPath;
+    constructor(opts) {
+        this.tb = opts.tbClient;
+        this.holdTtlMs = opts.holdTtlMs ?? DEFAULT_HOLD_TTL_MS;
+        this.dlqPath = opts.dlqPath ?? join(".usertrust", "dlq");
+    }
+    /**
+     * Create a PENDING hold for an AI compute action.
+     * The hold reserves tokens until settled (POST) or released (VOID).
+     */
+    async spendPending(p) {
+        const cost = estimateCost(p.action.model, p.action.inputTokens, p.action.outputTokens);
+        const userAccount = this.tb.getAccountId(p.userId);
+        const treasury = this.tb.getTreasuryId();
+        const bal = await this.tb.lookupBalance(userAccount);
+        if (bal.available < cost) {
+            throw new InsufficientBalanceError(p.userId, cost, bal.available);
+        }
+        const holdTimeoutSeconds = Math.ceil(this.holdTtlMs / 1000);
+        let pendingId;
+        try {
+            pendingId = await this.tb.createPendingTransfer({
+                debitAccountId: userAccount,
+                creditAccountId: treasury,
+                amount: cost,
+                code: XFER_SPEND,
+                timeoutSeconds: holdTimeoutSeconds,
+                userData64: deriveUserId64(p.userId),
+                ...(p.metadata?.agentRef ? { userData32: fnv1a32(p.metadata.agentRef) } : {}),
+            });
+        }
+        catch (err) {
+            if (isInsufficientBalanceError(err)) {
+                throw new InsufficientBalanceError(p.userId, cost, 0);
+            }
+            throw err;
+        }
+        return {
+            transferId: pendingId.toString(),
+            debitAccountId: userAccount.toString(),
+            creditAccountId: treasury.toString(),
+            amount: cost,
+            timestamp: new Date().toISOString(),
+            pending: true,
+        };
+    }
+    /**
+     * Settle a PENDING hold — debit is finalized.
+     * Optionally pass actual amount if less than the hold.
+     */
+    async postPendingSpend(transferId, actualAmount) {
+        try {
+            await this.tb.postTransfer(BigInt(transferId), actualAmount);
+        }
+        catch (err) {
+            // Post may have succeeded on TB but timed out — try to void
+            let voidSucceeded = false;
+            try {
+                await this.tb.voidTransfer(BigInt(transferId));
+                voidSucceeded = true;
+            }
+            catch {
+                // Both post and void failed — transfer state is ambiguous
+                writeDeadLetter({
+                    timestamp: new Date().toISOString(),
+                    source: "engine.postPendingSpend.ambiguous",
+                    transferId,
+                    payload: { actualAmount },
+                    error: "Both post and void failed — transfer state ambiguous",
+                }, this.dlqPath);
+                throw new Error(`Spend settlement ambiguous for transfer ${transferId}`);
+            }
+            if (voidSucceeded) {
+                throw new Error("Spend failed: pending transfer voided after post failure");
+            }
+        }
+    }
+    /**
+     * Release a PENDING hold — tokens returned to the user's available balance.
+     */
+    async voidPendingSpend(transferId) {
+        await this.tb.voidTransfer(BigInt(transferId));
+    }
+    /**
+     * Query balance for a user.
+     */
+    async balance(userId) {
+        const accountId = this.tb.getAccountId(userId);
+        return await this.tb.lookupBalance(accountId);
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/ledger/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/ledger/engine.ts"],"names":[],"mappings":"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"}

package/dist/ledger/pricing.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pricing table for the top 20 LLM models.
+ * All rates are in usertokens per 1,000 LLM tokens.
+ * 1 usertoken = $0.0001 (one basis point of a cent).
+ *
+ * Extracted from usertools platform — canonical pricing source.
+ */
+export interface ModelRates {
+    inputPer1k: number;
+    outputPer1k: number;
+}
+/**
+ * Pricing table for the top 20 models supported by the SDK.
+ * Key: model identifier as sent by the client.
+ */
+export declare const PRICING_TABLE: Record<string, ModelRates>;
+/** Fallback rate for unknown models (sonnet-class pricing). */
+export declare const FALLBACK_RATE: ModelRates;
+/**
+ * Look up rates by model string. Falls back to prefix matching,
+ * then FALLBACK_RATE for unknown models.
+ */
+export declare function getModelRates(model: string): ModelRates;
+/**
+ * Estimate cost in usertokens for a model call.
+ * Returns at least 1 (floor to prevent zero-amount transfers).
+ */
+export declare function estimateCost(model: string, inputTokens: number, outputTokens: number): number;
+/**
+ * Estimate input token count from a messages array.
+ * Heuristic: ~4 chars/token with a 1.5x safety margin so the PENDING
+ * hold exceeds actual cost in the vast majority of cases.
+ */
+export declare function estimateInputTokens(messages: unknown[]): number;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/ledger/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/ledger/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CA0CpD,CAAC;AAKF,+DAA+D;AAC/D,eAAO,MAAM,aAAa,EAAE,UAAiD,CAAC;AAE9E;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAUvD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAK7F;AA6BD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAqC/D"}

package/dist/ledger/pricing.js

@@ -0,0 +1,142 @@
+/**
+ * Pricing table for the top 20 LLM models.
+ * All rates are in usertokens per 1,000 LLM tokens.
+ * 1 usertoken = $0.0001 (one basis point of a cent).
+ *
+ * Extracted from usertools platform — canonical pricing source.
+ */
+/**
+ * Pricing table for the top 20 models supported by the SDK.
+ * Key: model identifier as sent by the client.
+ */
+export const PRICING_TABLE = {
+    // ── Anthropic ──
+    "claude-sonnet-4-6": { inputPer1k: 30, outputPer1k: 150 },
+    "claude-haiku-4-5": { inputPer1k: 10, outputPer1k: 50 },
+    "claude-opus-4-6": { inputPer1k: 50, outputPer1k: 250 },
+    // ── OpenAI ──
+    "gpt-4o": { inputPer1k: 25, outputPer1k: 100 },
+    "gpt-4o-mini": { inputPer1k: 1.5, outputPer1k: 6 },
+    "gpt-5.4": { inputPer1k: 25, outputPer1k: 150 },
+    o3: { inputPer1k: 20, outputPer1k: 80 },
+    "o4-mini": { inputPer1k: 5.5, outputPer1k: 22 },
+    // ── Google Gemini ──
+    "gemini-2.5-flash": { inputPer1k: 3, outputPer1k: 25 },
+    "gemini-2.5-pro": { inputPer1k: 12.5, outputPer1k: 100 },
+    "gemini-3.1-pro": { inputPer1k: 20, outputPer1k: 120 },
+    // ── Mistral ──
+    "mistral-large": { inputPer1k: 5, outputPer1k: 15 },
+    // ── DeepSeek ──
+    "deepseek-chat": { inputPer1k: 2.8, outputPer1k: 4.2 },
+    "deepseek-reasoner": { inputPer1k: 2.8, outputPer1k: 4.2 },
+    // ── xAI ──
+    "grok-3": { inputPer1k: 30, outputPer1k: 150 },
+    // ── Meta (via Bedrock) ──
+    "llama-4-maverick": { inputPer1k: 2.4, outputPer1k: 9.7 },
+    // ── Cohere ──
+    "command-a": { inputPer1k: 25, outputPer1k: 100 },
+    // ── Perplexity ──
+    "sonar-pro": { inputPer1k: 30, outputPer1k: 150 },
+    // ── Alibaba ──
+    "qwen-72b": { inputPer1k: 2.9, outputPer1k: 3.9 },
+    // ── Amazon ──
+    "nova-pro": { inputPer1k: 8, outputPer1k: 32 },
+};
+/** Pre-sorted entries for prefix matching (longest key first). */
+const SORTED_TABLE = Object.entries(PRICING_TABLE).sort((a, b) => b[0].length - a[0].length);
+/** Fallback rate for unknown models (sonnet-class pricing). */
+export const FALLBACK_RATE = { inputPer1k: 30, outputPer1k: 150 };
+/**
+ * Look up rates by model string. Falls back to prefix matching,
+ * then FALLBACK_RATE for unknown models.
+ */
+export function getModelRates(model) {
+    const exact = PRICING_TABLE[model];
+    if (exact)
+        return exact;
+    // Prefix match — longest key first prevents partial matches
+    for (const [key, rates] of SORTED_TABLE) {
+        if (model.startsWith(key))
+            return rates;
+    }
+    return FALLBACK_RATE;
+}
+/**
+ * Estimate cost in usertokens for a model call.
+ * Returns at least 1 (floor to prevent zero-amount transfers).
+ */
+export function estimateCost(model, inputTokens, outputTokens) {
+    const rates = getModelRates(model);
+    const inputCost = (inputTokens / 1000) * rates.inputPer1k;
+    const outputCost = (outputTokens / 1000) * rates.outputPer1k;
+    return Math.max(1, Math.ceil(inputCost + outputCost));
+}
+/**
+ * Estimate the block-level token count for a non-text content block.
+ * Extracts textual payload where possible, falls back to serialised length.
+ */
+function estimateBlockTokens(block) {
+    let chars = 0;
+    if (typeof block.text === "string")
+        chars += block.text.length;
+    if (typeof block.content === "string")
+        chars += block.content.length;
+    // Handle nested arrays (tool_result payloads)
+    if (Array.isArray(block.content)) {
+        for (const item of block.content) {
+            if (typeof item === "string") {
+                chars += item.length;
+            }
+            else if (item != null && typeof item === "object") {
+                chars += JSON.stringify(item).length;
+            }
+        }
+    }
+    // Conservative fallback for unknown/binary shapes
+    if (chars === 0)
+        chars = JSON.stringify(block).length;
+    return Math.ceil(chars / 4);
+}
+/**
+ * Estimate input token count from a messages array.
+ * Heuristic: ~4 chars/token with a 1.5x safety margin so the PENDING
+ * hold exceeds actual cost in the vast majority of cases.
+ */
+export function estimateInputTokens(messages) {
+    if (!Array.isArray(messages))
+        return 1;
+    let textChars = 0;
+    let blockTokens = 0;
+    for (const msg of messages) {
+        if (msg == null || typeof msg !== "object")
+            continue;
+        const m = msg;
+        // ~4 tokens per-message overhead (role, structure)
+        textChars += 16;
+        const content = m.content;
+        if (typeof content === "string") {
+            textChars += content.length;
+        }
+        else if (Array.isArray(content)) {
+            for (const block of content) {
+                if (block == null || typeof block !== "object")
+                    continue;
+                const b = block;
+                if (b.type === "text" && typeof b.text === "string") {
+                    textChars += b.text.length;
+                }
+                else {
+                    blockTokens += estimateBlockTokens(b);
+                }
+            }
+        }
+        // Tool-call overhead
+        if (typeof m.tool_call_id === "string")
+            blockTokens += 10;
+    }
+    const textTokens = Math.ceil(textChars / 4);
+    const raw = textTokens + blockTokens;
+    // 1.5x safety margin
+    return Math.max(1, Math.ceil(raw * 1.5));
+}
+//# sourceMappingURL=pricing.js.map

package/dist/ledger/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../../src/ledger/pricing.ts"],"names":[],"mappings":"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"}

package/dist/memory/patterns.d.ts

@@ -0,0 +1,35 @@
+export interface PatternEntry {
+    promptHash: string;
+    model: string;
+    cost: number;
+    success: boolean;
+    timestamp: string;
+}
+export interface PatternStats {
+    totalEntries: number;
+    uniqueModels: number;
+    hitCount: Map<string, number>;
+}
+/** Reset internal state — for testing only. */
+export declare function _resetPatternCache(): void;
+/**
+ * Hash prompt text with SHA-256. Never store raw prompts.
+ */
+export declare function hashPrompt(text: string): string;
+/**
+ * Record a pattern entry from a completed LLM call.
+ * Appends to `.usertools/patterns/memory.json`.
+ * Evicts oldest entries when exceeding 10,000.
+ */
+export declare function recordPattern(entry: Omit<PatternEntry, "timestamp">, vaultPath?: string): Promise<void>;
+/**
+ * Suggest the best model for a given prompt hash based on past patterns.
+ * Returns the model with the best cost-adjusted success ratio, or null if
+ * no patterns exist for this prompt hash.
+ */
+export declare function suggestModel(promptHash: string, vaultPath?: string): string | null;
+/**
+ * Return summary statistics for all stored patterns.
+ */
+export declare function getPatternStats(vaultPath?: string): Promise<PatternStats>;
+//# sourceMappingURL=patterns.d.ts.map

package/dist/memory/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/memory/patterns.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,YAAY;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAoCD,+CAA+C;AAC/C,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAuCD;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAClC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,EACtC,SAAS,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA6ClF;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAgB/E"}

package/dist/memory/patterns.js

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { VAULT_DIR } from "../shared/constants.js";
+// ── Constants ──
+const PATTERNS_DIR = "patterns";
+const MEMORY_FILE = "memory.json";
+const MAX_ENTRIES = 10_000;
+const cacheByVault = new Map();
+function resolveVaultKey(vaultPath) {
+    return vaultPath ?? VAULT_DIR;
+}
+function getCache(vaultPath) {
+    const key = resolveVaultKey(vaultPath);
+    let entry = cacheByVault.get(key);
+    if (entry === undefined) {
+        entry = { entries: [], initialized: false };
+        cacheByVault.set(key, entry);
+    }
+    return entry;
+}
+function memoryFilePath(vaultPath) {
+    const base = vaultPath ?? VAULT_DIR;
+    return join(base, PATTERNS_DIR, MEMORY_FILE);
+}
+/** Reset internal state — for testing only. */
+export function _resetPatternCache() {
+    cacheByVault.clear();
+}
+// ── Internals ──
+async function ensureLoaded(vaultPath) {
+    const cache = getCache(vaultPath);
+    if (cache.initialized) {
+        return cache.entries;
+    }
+    const filePath = memoryFilePath(vaultPath);
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            cache.entries = [];
+        }
+        else {
+            cache.entries = parsed;
+        }
+    }
+    catch {
+        // File doesn't exist or is corrupt — start fresh
+        cache.entries = [];
+    }
+    cache.initialized = true;
+    return cache.entries;
+}
+async function persist(entries, vaultPath) {
+    const filePath = memoryFilePath(vaultPath);
+    const dir = dirname(filePath);
+    await mkdir(dir, { recursive: true });
+    // Atomic write via rename
+    const tmpPath = `${filePath}.tmp.${Date.now()}`;
+    await writeFile(tmpPath, JSON.stringify(entries, null, "\t"), "utf-8");
+    await rename(tmpPath, filePath);
+}
+// ── Public API ──
+/**
+ * Hash prompt text with SHA-256. Never store raw prompts.
+ */
+export function hashPrompt(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/**
+ * Record a pattern entry from a completed LLM call.
+ * Appends to `.usertools/patterns/memory.json`.
+ * Evicts oldest entries when exceeding 10,000.
+ */
+export async function recordPattern(entry, vaultPath) {
+    const entries = await ensureLoaded(vaultPath);
+    const full = {
+        ...entry,
+        timestamp: new Date().toISOString(),
+    };
+    entries.push(full);
+    // Evict oldest if over capacity
+    if (entries.length > MAX_ENTRIES) {
+        const excess = entries.length - MAX_ENTRIES;
+        entries.splice(0, excess);
+    }
+    const cache = getCache(vaultPath);
+    cache.entries = entries;
+    await persist(entries, vaultPath);
+}
+/**
+ * Suggest the best model for a given prompt hash based on past patterns.
+ * Returns the model with the best cost-adjusted success ratio, or null if
+ * no patterns exist for this prompt hash.
+ */
+export function suggestModel(promptHash, vaultPath) {
+    const cache = getCache(vaultPath);
+    if (!cache.initialized || cache.entries.length === 0) {
+        return null;
+    }
+    // Filter entries matching this prompt hash
+    const matching = cache.entries.filter((e) => e.promptHash === promptHash);
+    if (matching.length === 0) {
+        return null;
+    }
+    // Group by model, compute success rate / average cost
+    const modelStats = new Map();
+    for (const entry of matching) {
+        let stats = modelStats.get(entry.model);
+        if (stats === undefined) {
+            stats = { successes: 0, total: 0, totalCost: 0 };
+            modelStats.set(entry.model, stats);
+        }
+        stats.total += 1;
+        stats.totalCost += entry.cost;
+        if (entry.success) {
+            stats.successes += 1;
+        }
+    }
+    // Score: success_rate / avg_cost (higher is better)
+    // If avg_cost is 0, treat as very efficient (use large score)
+    let bestModel = null;
+    let bestScore = -1;
+    for (const [model, stats] of modelStats) {
+        const successRate = stats.successes / stats.total;
+        const avgCost = stats.totalCost / stats.total;
+        const score = avgCost > 0 ? successRate / avgCost : successRate * 1_000_000;
+        if (score > bestScore) {
+            bestScore = score;
+            bestModel = model;
+        }
+    }
+    return bestModel;
+}
+/**
+ * Return summary statistics for all stored patterns.
+ */
+export async function getPatternStats(vaultPath) {
+    const entries = await ensureLoaded(vaultPath);
+    const models = new Set();
+    const hitCount = new Map();
+    for (const entry of entries) {
+        models.add(entry.model);
+        hitCount.set(entry.promptHash, (hitCount.get(entry.promptHash) ?? 0) + 1);
+    }
+    return {
+        totalEntries: entries.length,
+        uniqueModels: models.size,
+        hitCount,
+    };
+}
+//# sourceMappingURL=patterns.js.map

package/dist/memory/patterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.js","sourceRoot":"","sources":["../../src/memory/patterns.ts"],"names":[],"mappings":"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"}

package/dist/policy/decay.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Decay Rate Calculator
+ *
+ * Calculates exponential decay rates for quota/budget consumption.
+ * Enables time-weighted rate limiting that rewards idle periods.
+ *
+ * The decay model uses: value(t) = initial * e^(-lambda * t)
+ * where lambda is the decay constant and t is time elapsed.
+ *
+ * Adapted from Field Project fermion/src/higgs/decay-rate.ts.
+ */
+/** Configuration for decay rate calculation. */
+export interface DecayConfig {
+    /** Half-life in milliseconds — time for value to decay to 50%. */
+    halfLifeMs: number;
+    /** Minimum threshold below which value is considered zero. */
+    minThreshold?: number;
+}
+/** A timestamped entry for weighted sum calculation. */
+export interface TimestampedEntry {
+    /** Timestamp in milliseconds (e.g. Date.now()) */
+    ts: number;
+    /** The value at that timestamp */
+    value: number;
+}
+/** Result of a decay rate calculation. */
+export interface DecayResult {
+    /** The decayed value. */
+    decayedValue: number;
+    /** The decay factor applied (0-1). */
+    decayFactor: number;
+    /** Time elapsed since reference point (ms). */
+    elapsedMs: number;
+    /** Whether the value has decayed below threshold. */
+    fullyDecayed: boolean;
+}
+/**
+ * Decay rate calculator using exponential decay model.
+ *
+ * Used for time-weighted rate limiting. Older consumption contributes less
+ * to current budget usage, rewarding tenants who space out their requests.
+ */
+export declare class DecayRateCalculator {
+    /** Decay constant (lambda = ln(2) / halfLife) */
+    private readonly lambda;
+    /** Minimum threshold for considering a value "fully decayed" */
+    private readonly minThreshold;
+    constructor(config: DecayConfig);
+    /**
+     * Calculate the decayed value after a given time elapsed.
+     *
+     * @param initialValue - The original value before decay
+     * @param elapsedMs - Time elapsed in milliseconds
+     * @returns Decay result with decayed value and metadata
+     */
+    calculate(initialValue: number, elapsedMs: number): DecayResult;
+    /**
+     * Calculate the weighted sum of multiple timestamped values.
+     * Each value is decayed based on its age relative to the reference time.
+     *
+     * @param entries - Array of timestamped entries
+     * @param referenceTime - The reference time (usually Date.now())
+     * @returns Total decayed value
+     */
+    calculateWeightedSum(entries: TimestampedEntry[], referenceTime?: number): number;
+    /**
+     * Calculate time required for a value to decay to a target.
+     *
+     * @param currentValue - Current value
+     * @param targetValue - Target value to decay to
+     * @returns Time in milliseconds, or Infinity if target >= current
+     */
+    timeToDecay(currentValue: number, targetValue: number): number;
+    /**
+     * Get the half-life of this calculator.
+     */
+    getHalfLifeMs(): number;
+}
+/**
+ * Calculate the decay rate for a set of timestamped entries.
+ *
+ * This is the primary entry point — a pure function that creates a calculator,
+ * computes the weighted sum, and returns the total decayed value.
+ *
+ * @param entries - Array of timestamped entries
+ * @param halfLife - Half-life in milliseconds (default: 1 hour)
+ * @returns Total decayed value (weighted sum)
+ */
+export declare function calculateDecayRate(entries: TimestampedEntry[], halfLife?: number): number;
+/**
+ * Create a decay calculator with a half-life matching a cost window.
+ * The half-life is set to 1/4 of the window so most decay occurs within it.
+ */
+export declare function createCostDecayCalculator(windowMs: number): DecayRateCalculator;
+//# sourceMappingURL=decay.d.ts.map

package/dist/policy/decay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decay.d.ts","sourceRoot":"","sources":["../../src/policy/decay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC3B,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAChC,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;CACd;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC3B,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,YAAY,EAAE,OAAO,CAAC;CACtB;AAMD;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC/B,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,MAAM,EAAE,WAAW;IAQ/B;;;;;;OAMG;IACH,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW;IA0B/D;;;;;;;OAOG;IACH,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,aAAa,GAAE,MAAmB,GAAG,MAAM;IAiB7F;;;;;;OAMG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAS9D;;OAEG;IACH,aAAa,IAAI,MAAM;CAGvB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,QAAQ,SAAY,GAAG,MAAM,CAG5F;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAK/E"}