@bivelio/savings-layer 0.4.19 → 0.4.21

package/dist/index.d.ts

@@ -205,7 +205,7 @@ declare function precioDeLista(model: string): CostModel | undefined;
  * on the customer's machine. `test/version-declarada.test.ts` ties this
  * constant to package.json so the two can never drift.
  */
-declare const BV_SALA_VERSION = "0.4.19";
+declare const BV_SALA_VERSION = "0.4.21";
 
 /**
  * Environment-agnostic UUID generation.
@@ -990,6 +990,15 @@ interface LicenseGate {
      * que tener una rama por defecto de todas formas.
      */
     status?(): string;
+    /**
+     * Why the key does not open, when it does not; `undefined` when it does. It
+     * only refines the MESSAGE, never the verdict: an `"invalid"` whose reason is
+     * `"malformed"` (not even the shape of a token: the `bvk_` pasted where the
+     * license goes) gets different advice from an `"invalid"` that has the shape
+     * but no valid signature. Optional because a gate is implemented by the
+     * caller; without it, the generic message for that status.
+     */
+    reason?(): string | undefined;
 }
 interface TraceEvent {
     stage: string;
@@ -1686,10 +1695,46 @@ interface ToolSelectorOptions {
     maxTools?: number;
     /** Tokenizer-aware scorer for tie-breaking (optional). */
     scoreIntentMatch?: (text: string, tool: ToolDescriptor) => number;
+    /**
+     * How many requests are selected by relevance before the set is FROZEN for a
+     * given key. Below this count the selector learns; past it, it always emits
+     * the same set and `setIsStable` is true again.
+     *
+     * The default of 16 is measured, not round: across 214 sessions of real
+     * traffic, a set frozen from the first 16 invoked tools came up short in
+     * 0.0% of sessions (8 fell short in 2.3%, 12 in 0.5%).
+     */
+    learningTurns?: number;
+    /** Where frozen sets are remembered. Defaults to an in-process map. */
+    freezer?: ToolSetFreezer;
+}
+/**
+ * Memory for the frozen tool set. The caller owns the key: the pipeline passes
+ * the caller's toolset hash, which in practice is one key per session.
+ */
+interface ToolSetFreezer {
+    read(key: string): {
+        ids: string[];
+        turns: number;
+    } | undefined;
+    record(key: string, ids: string[], turns: number): void;
+}
+/** In-process freezer with a key cap (clears wholesale when full). */
+declare class InMemoryToolSetFreezer implements ToolSetFreezer {
+    private readonly cap;
+    private map;
+    constructor(cap?: number);
+    read(key: string): {
+        ids: string[];
+        turns: number;
+    } | undefined;
+    record(key: string, ids: string[], turns: number): void;
 }
 declare class ToolSelector {
     private readonly maxTools;
     private readonly scoreIntentMatch;
+    private readonly learningTurns;
+    private readonly freezer;
     constructor(opts?: ToolSelectorOptions);
     /**
      * Todas las herramientas que pasó el llamante, acotadas SOLO por el
@@ -1704,7 +1749,13 @@ declare class ToolSelector {
      * pasaría a fallar en duro.
      */
     passthrough(tools: ToolDescriptor[] | undefined): ToolSelection;
-    select(text: string, tools: ToolDescriptor[] | undefined, execution: ExecutionClass): ToolSelection;
+    select(text: string, tools: ToolDescriptor[] | undefined, execution: ExecutionClass, 
+    /**
+     * Freeze key. The pipeline passes the caller's toolset hash, which in
+     * practice is one key per session. Without a key nothing is frozen and the
+     * selector behaves exactly as before.
+     */
+    freezeKey?: string): ToolSelection;
 }
 
 /**
@@ -2533,8 +2584,14 @@ declare class LicenseError extends Error {
  *
  * El comportamiento no cambia —sigue siendo fail-closed, `granted()` no lo
  * concede— pero ahora el mensaje puede decir la verdad.
+ *
+ * `none` means "there is no key": what is left after `normalizeLicenseKey` is
+ * EMPTY. It is the same value `LicenseError.status` already carries when nothing
+ * was configured, because it is the same problem with the same fix: a
+ * `licenseKey: "   "` (an empty environment variable, a blank secret file) used
+ * to tell the customer their key "does not verify" — there was no key.
  */
-type LicenseStatus = "active" | "grace" | "expired" | "invalid" | "revoked" | "stale";
+type LicenseStatus = "active" | "grace" | "expired" | "invalid" | "revoked" | "stale" | "none";
 /** Decoded license token body (mirror of `@bivelio/protocol`'s LicensePayload,
  *  declared locally so the SDK stays free of a control-plane dependency). */
 interface LicenseTokenPayload {
@@ -2579,6 +2636,48 @@ interface LicenseKeyset {
 }
 /** Narrow a verification key to a {@link LicenseKeyset} (vs a bare SPKI PEM string). */
 declare function isKeyset(k: string | LicenseKeyset): k is LicenseKeyset;
+/**
+ * Normalize a license key the way it arrives from the real world — ONCE, at the
+ * entry point, never inside the verifier.
+ *
+ * The README says `export BIVELIO_LICENSE_KEY=…` and dotenv trims, so that path
+ * never showed it. But anyone reading the key from a file (`readFileSync`), from
+ * a Docker/Kubernetes secret (mounted as a file, trailing newline included) or
+ * copying it out of an `Authorization` header handed over a CORRECT key with a
+ * `\n` after it, a space before it, quotes around it or a `Bearer ` in front —
+ * and the SDK answered "does not verify, check you pasted the WHOLE key". A
+ * wrong diagnosis on a good key is the worst possible hint: it sends the
+ * customer to look where the problem is not.
+ *
+ * Worse, it was INCONSISTENT: `tok + "\r\n"` passed and `tok + "\n"` did not,
+ * because `atob` ignores ASCII whitespace while the padding was computed from a
+ * length that included it, and two extra characters give the same remainder
+ * modulo 4 as zero. Behavior that depends on which editor saved the file is not
+ * behavior.
+ *
+ * Only OUTER wrapping is removed — whitespace, one pair of single or double
+ * quotes, a `Bearer` prefix in any capitalization — in that order, in one pass.
+ * Anything INSIDE the key is left alone: an interior space is not wrapping, it
+ * is a broken key, and {@link licenseKeyShape} reports it as `malformed`.
+ */
+declare function normalizeLicenseKey(raw: string): string;
+/**
+ * The SHAPE of an already-normalized key, so the error message can tell apart
+ * three problems that used to get the same text:
+ *
+ *   · `empty`     — there is no key (only whitespace, or nothing at all).
+ *   · `malformed` — not even the shape of a token: not three dot-separated
+ *                   base64url segments. This is where the `bvk_` service key
+ *                   pasted where the license goes lands, as does arbitrary text
+ *                   or a token with a line break in the middle.
+ *   · `token`     — has the shape; whether it verifies is up to the signature.
+ *
+ * It is the SAME shape rule {@link verifyCompactSignature} enforces, so that "has
+ * the shape" and "verification was attempted" mean the same thing.
+ */
+type LicenseKeyShape = "empty" | "malformed" | "token";
+/** Classify a normalized key. See {@link LicenseKeyShape}. */
+declare function licenseKeyShape(normalizedKey: string): LicenseKeyShape;
 /**
  * Verify the Ed25519 signature of any BV-SALA compact token
  * (`base64url(header).base64url(body).base64url(sig)`, sig over `${head}.${body}`)
@@ -2587,6 +2686,13 @@ declare function isKeyset(k: string | LicenseKeyset): k is LicenseKeyset;
  * so the browser (`@noble/curves`) and node (`node:crypto`) sides agree byte-for-byte
  * and there is no bespoke per-message verification path to keep in sync. It does NOT
  * interpret the payload or the header `typ` — callers do that.
+ *
+ * Shape is checked SEGMENT by segment, not just by counting dots. Three parts
+ * used to be enough and the rest was left to `atob`, which ignores whitespace:
+ * that is how a token with `\r\n` after it verified while the same token with
+ * `\n` did not (see {@link normalizeLicenseKey}). The shared primitive must give
+ * the same answer to the same input, always; a caller that wants to tolerate
+ * wrapping normalizes BEFORE calling.
  */
 declare function verifyCompactSignature(token: string, publicKey: string | LicenseKeyset): CompactVerification;
 /** Verify a token's signature and decode its payload. Does not check expiry. */
@@ -2614,6 +2720,9 @@ declare function deriveStatus(payload: {
  * Verify + apply the grace policy → a resolved status. Mirrors what the issuing
  * control plane resolves for the same token. Bad signature / malformed
  * → invalid; otherwise the status comes from {@link deriveStatus}.
+ *
+ * A public entry point, so it normalizes like the others (gate and refresher):
+ * the same key must resolve the same whichever way it comes in.
  */
 declare function resolveLicense(token: string, publicKey: string | LicenseKeyset, opts?: {
     nowSeconds?: number;
@@ -2690,6 +2799,15 @@ declare class RevocationSnapshot {
 interface ResolvedGate extends LicenseGate {
     isActive(): boolean;
     status(): LicenseStatus;
+    /**
+     * Why the key does not open, when it does not; `undefined` when it verified.
+     * Under `status() === "invalid"` it tells a key that does NOT EVEN HAVE THE
+     * SHAPE of a token (`"malformed"`: the `bvk_` pasted where the license goes,
+     * arbitrary text) from a well-formed one whose signature fails (the verifier's
+     * reason, e.g. `"bad signature"`). Both are `invalid` — the stable handle for
+     * branching does not change — but the advice given to the customer differs.
+     */
+    reason(): string | undefined;
     /** Unix seconds after which the online status should be re-checked (poller anchor). */
     refreshAfter?(): number | undefined;
 }
@@ -3021,6 +3139,11 @@ interface SavingsLayerConfig {
      * against the embedded public key and builds a {@link licenseGate} from it.
      * Without a valid, active license (and without {@link devUnlicensed}), the
      * pipeline refuses to run — get a key at https://savings.bivelio.com.
+     *
+     * Surrounding whitespace (the trailing newline of a file or mounted secret),
+     * wrapping quotes and a `Bearer ` prefix are stripped before verification, so
+     * a key read with `readFileSync` works as-is. Anything INSIDE the key is not
+     * touched: a key with a space in the middle is a broken key.
      */
     licenseKey?: string;
     /**
@@ -3324,4 +3447,4 @@ interface SavingsLayer {
  */
 declare function createSavingsLayer(config: Omit<SavingsLayerConfig, "tokenizer"> & Partial<Pick<SavingsLayerConfig, "tokenizer">>): SavingsLayer;
 
-export { type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BivelioHandoff, CATALOGO, COMPACT_ROWS_INSTRUCTION, type CacheOutcome, type CacheTier, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactVerification, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, DEFAULT_COST_MODEL, DEFAULT_MAX_STALENESS_SECONDS, type DeferredExecutionReport, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, type JsonSchema, LicenseError, type LicenseGate, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRECIOS_AL_DIA, type Policy, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderUsage, QUALITY_STATUSES, type QualityStatus, type RequestContext, type Reranker, type ResolvedDeps, type ResolvedGate, type ResolvedLicense, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RevocationListBody, type RevocationListVerification, type RevocationPollEvent, RevocationPoller, type RevocationPollerOptions, RevocationSnapshot, type RouteDecision, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsReport, type SavingsRequest, type SavingsResult, type SavingsToggles, SchemaRegistry, type SemanticCacheOptions, type SemanticHit, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, TraceCollector, type TraceEvent, UMBRAL_LOCAL, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, compactRowsSerializer, compresionFiel, computeNextDelay, cosine, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, embebedorLocal, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, liveGateFromKey, mergeDelta, modelFamilyOf, multisetEqual, negationCount, noopCompressor, normalizeText, numericTokens, precioDeLista, projectContext, providerNativeBackend, randomId, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, uniformColumns, validateAgainstSchema, vectorLocal, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans, words };
+export { type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BivelioHandoff, CATALOGO, COMPACT_ROWS_INSTRUCTION, type CacheOutcome, type CacheTier, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactVerification, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, DEFAULT_COST_MODEL, DEFAULT_MAX_STALENESS_SECONDS, type DeferredExecutionReport, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, InMemoryToolSetFreezer, type JsonSchema, LicenseError, type LicenseGate, type LicenseKeyShape, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRECIOS_AL_DIA, type Policy, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderUsage, QUALITY_STATUSES, type QualityStatus, type RequestContext, type Reranker, type ResolvedDeps, type ResolvedGate, type ResolvedLicense, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RevocationListBody, type RevocationListVerification, type RevocationPollEvent, RevocationPoller, type RevocationPollerOptions, RevocationSnapshot, type RouteDecision, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsReport, type SavingsRequest, type SavingsResult, type SavingsToggles, SchemaRegistry, type SemanticCacheOptions, type SemanticHit, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToolSetFreezer, TraceCollector, type TraceEvent, UMBRAL_LOCAL, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, compactRowsSerializer, compresionFiel, computeNextDelay, cosine, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, embebedorLocal, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, licenseKeyShape, liveGateFromKey, mergeDelta, modelFamilyOf, multisetEqual, negationCount, noopCompressor, normalizeLicenseKey, normalizeText, numericTokens, precioDeLista, projectContext, providerNativeBackend, randomId, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, uniformColumns, validateAgainstSchema, vectorLocal, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans, words };