यह कैसे काम करता है

सिग्नेचर एल्गोरिदम, मिलान सटीक क्यों है, और लेजर वास्तव में क्या रिकॉर्ड करता है।

सिग्नेचर

हर निर्णय को कैश कुंजी के रूप में उपयोग करने से पहले एक स्थिर सिग्नेचर में सामान्यीकृत किया जाता है:

export function signature(decision: Decision): string {
  const normalized = {
    intent: decision.intent,
    params: sortKeysDeep(decision.params),
  };
  return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
}

सामान्यीकरण जानबूझकर सतही है — ऑब्जेक्ट कुंजियों को पुनरावर्ती रूप से क्रमबद्ध किया जाता है, इसलिए { a: 1, b: 2 } और { b: 2, a: 1 } का हैश एक जैसा होता है, लेकिन intent या पैरामीटर मानों के बारे में कुछ भी नहीं बदला जाता। इसमें न स्टेमिंग है, न केस-फोल्डिंग, न अर्थगत मानकीकरण।

{ intent: "summarize_pr", params: { repo: "acme/widgets", pr: 482 } }
{ intent: "summarize_pr", params: { pr: 482, repo: "acme/widgets" } }
        │                                       │
        └──────────────── same signature ──────┘

{ intent: "summarize_pr", params: { repo: "acme/widgets", pr: 483 } }
        │
        └── different signature (different pr) ──┘

अर्थगत मिलान नहीं, सटीक मिलान क्यों

अर्थगत/फज़ी कैश अधिक दोहराव पकड़ता — “summarize this PR” और “give me a summary of this pull request” दोनों हिट होते। लेकिन इसका अर्थ यह भी होता कि Runic को तय करना पड़ता कि अलग-अलग ढंग से लिखे गए दो अनुरोध कैश किया गया उत्तर साझा करने के लिए पर्याप्त रूप से समान हैं या नहीं, और ठीक ऐसे ही गैर-नियतात्मक निर्णय लेने से बचने के लिए Runic बनाया गया है।

सटीक मिलान का अर्थ है कि कैश हिट सिद्ध रूप से वही निर्णय है, न कि संभवतः वही निर्णय। इसकी कीमत यह है कि कॉलरों को params में शामिल चीज़ों के बारे में सोच-समझकर निर्णय लेना होता है — त्वरित शुरुआत देखें।

लेजर क्या रिकॉर्ड करता है

लेजर केवल-जोड़ने वाला लॉग है, ऐसा चल रहा कुल योग नहीं जो भटक सकता है:

interface LedgerEvent {
  signature: string;
  kind: "hit" | "miss";
  tokensSpent: number;
  timestamp: number;
}

• मिस होने पर, Runic आर्टिफैक्ट बनाने के लिए आपके कोड द्वारा रिपोर्ट किया गया tokensSpent लॉग करता है।
• हिट होने पर, Runic उस सिग्नेचर के मूल मिस को खोजता है और सहेजा गया वही tokensSpent मान लॉग करता है — कभी अनुमान नहीं, कभी अंदाज़ा नहीं। यदि किसी तरह हिट हो रहे सिग्नेचर के लिए कोई पूर्व मिस मौजूद नहीं है, तो यह संख्या गढ़ने के बजाय 0 लॉग करता है।

summary.totalSpent = sum of all miss events
summary.totalSaved = sum of all hit events
tokensWithoutRunic = totalSpent + totalSaved   (what it would've cost with no cache at all)
savingsPercent     = totalSaved / tokensWithoutRunic

Runic स्वयं कभी टोकन लागत नहीं मापता। यह केवल वही दोहराता है जो कॉलिंग कोड ने उसे storeResult(decision, artifact, tokensSpent) के माध्यम से बताया था — वास्तविक API प्रतिक्रिया से अनुमान के बजाय वह संख्या openrouter-savings कैसे प्राप्त करता है, इसके लिए बेंचमार्क देखें।

स्टोरेज बैकएंड

@runic-labs/cache और @runic-labs/ledger दोनों एक छोटे स्टोरेज इंटरफ़ेस के विरुद्ध बनाए गए हैं, जिनके दो कार्यान्वयन v1 में शामिल हैं:

v1 में दोनों प्रति-सेशन स्कोप में हैं — क्रॉस-सेशन साझाकरण को अभी जोड़ देने के बजाय जानबूझकर बाद के चरण में क्यों रखा गया है, इसके लिए स्कोप देखें।

पुरानापन केवल सलाहकारी है

कैश प्रविष्टियों में एक stale फ़्लैग होता है, जिसे कॉन्फ़िगर करने योग्य विंडो (डिफ़ॉल्ट रूप से 24 घंटे) से गणना किया जाता है। Runic कभी भी पुरानी प्रविष्टि को स्वचालित रूप से हटाता या अस्वीकार नहीं करता — यह कॉलर के लिए ऐसी जानकारी है जिस पर वह चाहे तो कार्रवाई कर सकता है, न कि कोई प्रवर्तन तंत्र। यदि आपके उपयोग के मामले में कठोर समाप्ति चाहिए, तो स्वयं entry.stale जाँचें और तय करें कि उसके साथ क्या करना है।