@takk/racs 1.0.0

package/dist/edge/index.d.ts

@@ -0,0 +1,598 @@
+import { l as RACSOptions, R as RACS, h as PricingTable, c as CacheUsage, j as ProviderId, L as LedgerStats, e as LintFinding, P as PlanInput, k as ProviderProfile, g as Pricing, C as CacheDirective, B as BreakEven, K as KvLike, S as StateBackend } from '../types-DQ7-9sk3.js';
+export { A as AdapterFamily, a as CachePlan, b as CacheTtl, D as DriftReport, E as ExpectedReuse, d as LintCode, f as PrefixStats, i as PromptSegment, m as RefreshEntry, n as SegmentRole, o as Stability, p as StateSnapshot, T as TelemetryEvent, q as TelemetryListener } from '../types-DQ7-9sk3.js';
+
+/**
+ * Engine core of RACS (Remote Agent Context Store): wires the analyzer, the planner, the
+ * ledger, drift fingerprints, the keep-warm keeper, and the resource registry behind the
+ * one public {@link RACS} surface.
+ *
+ * The core owns everything stateful: deterministic plan identity, prefix bookkeeping,
+ * telemetry fan-out, and persistence. The modules it wires stay pure or self-contained, so
+ * this file is the only place where their interactions are decided.
+ *
+ * Determinism: plan ids derive from a seeded counter ({@link RACSOptions.seed}, default 7)
+ * through the seeded short-id generator, never from the platform UUID or the global random
+ * generator. The clock is read once per mutating call and is injectable for tests.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Creates one RACS (Remote Agent Context Store) engine, the single entry point of the
+ * package. Zero-config by default: no options yields a fully working in-memory engine with
+ * the shipped provider profiles, seed 7, a 1000-prefix cap, and the platform wall clock.
+ *
+ * Persistence note: when {@link RACSOptions.state} is given, the previous snapshot is
+ * restored asynchronously after construction, section by section, skipping anything
+ * corrupt. Hosts that need restored state before their first plan should `await
+ * racs.flush()` once after construction, flush waits for the restore to settle.
+ *
+ * @param options - See {@link RACSOptions}, every field optional.
+ * @returns The engine, see {@link RACS} for the full surface contract.
+ *
+ * @example
+ * ```ts
+ * const racs = createRACS({ seed: 42 });
+ * const plan = racs.plan({
+ *   provider: 'anthropic',
+ *   model: 'claude-sonnet-4-5',
+ *   segments: [
+ *     { id: 'system', role: 'system', stability: 'stable', content: SYSTEM_PROMPT },
+ *     { id: 'turn', role: 'dynamic', stability: 'volatile', content: userTurn },
+ *   ],
+ *   reuse: { intervalSeconds: 60 },
+ * });
+ * // Apply plan.directives to the API call the host owns, then report usage back:
+ * racs.record({ provider: 'anthropic', model: 'claude-sonnet-4-5', prefixKey: plan.prefixKey,
+ *   inputTokens: 5000, cacheReadTokens: 4200 });
+ * ```
+ */
+declare function createRACS(options?: RACSOptions): RACS;
+
+/**
+ * Error model for RACS (Remote Agent Context Store).
+ *
+ * RACS throws exactly one error class so that host applications can catch and branch on a
+ * single type, then dispatch on the stable machine-readable {@link RacsError.code}. New codes
+ * may be added in minor versions, so consumers must treat the code space as open and fall back
+ * gracefully on codes they do not recognize.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The only error type thrown by RACS.
+ *
+ * Invariants:
+ * - `name` is always the literal string `'RacsError'`, safe for cross-realm checks where
+ *   `instanceof` fails (multiple bundles, workers, iframes).
+ * - `code` is a stable, machine-readable, SCREAMING_SNAKE identifier prefixed with `ERR_`.
+ *   It never changes meaning across versions, although new codes may appear in minors.
+ * - `message` is human-readable English prose intended for logs, never for parsing.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   racs.plan(input);
+ * } catch (error) {
+ *   if (error instanceof RacsError && error.code === 'ERR_INVALID_INPUT') {
+ *     // The caller sent a malformed PlanInput, fix the call site.
+ *   }
+ * }
+ * ```
+ */
+declare class RacsError extends Error {
+    /**
+     * Stable machine-readable error code, for example `'ERR_INVALID_INPUT'`.
+     *
+     * Branch on this field, never on `message`. The code space is minor-extensible.
+     */
+    readonly code: string;
+    /**
+     * @param message - Human-readable description of what went wrong and how to fix it.
+     * @param code - Stable machine-readable code, see {@link RacsError.code}.
+     */
+    constructor(message: string, code: string);
+    /**
+     * Builds a {@link RacsError} with code `'ERR_INVALID_INPUT'`.
+     *
+     * Used for every caller-side contract violation: malformed segments, a segment carrying
+     * neither `content` nor `contentHash`, negative token counts, unknown TTL strings, and any
+     * other input the type system cannot reject for untyped JavaScript callers.
+     *
+     * @param message - Human-readable description of the invalid input.
+     * @returns A new error instance, never thrown by this factory itself.
+     */
+    static invalid(message: string): RacsError;
+}
+
+/**
+ * Usage ledger of RACS (Remote Agent Context Store): aggregates normalized provider usage
+ * reports into per-prefix and ledger-wide hit ratios and USD savings.
+ *
+ * The ledger holds aggregates only, never prompt content, so its serialized form leaks
+ * nothing. It is synchronous, allocation-light, and bounded: at most `maxPrefixes` distinct
+ * prefixes are tracked, with least-recently-used eviction beyond that.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * One serialized prefix aggregate, see {@link LedgerJSON}.
+ */
+interface LedgerEntryJSON {
+    /** Aggregate key: the usage `prefixKey`, or `provider:model` for plan-less usage. */
+    readonly key: string;
+    /** Provider of the aggregated calls. */
+    readonly provider: ProviderId;
+    /** Model of the aggregated calls, the {@link PricingTable} lookup key. */
+    readonly model: string;
+    /** Number of usage records aggregated. */
+    readonly calls: number;
+    /** Total tokens served from cache. */
+    readonly readTokens: number;
+    /** Total tokens written to 5-minute-TTL caches. */
+    readonly write5mTokens: number;
+    /** Total tokens written to 1-hour-TTL caches. */
+    readonly write1hTokens: number;
+    /** Total input tokens that were neither read from nor written to cache. */
+    readonly uncachedTokens: number;
+}
+/**
+ * Serialized ledger state, the shape produced by {@link Ledger.toJSON} and consumed by
+ * {@link Ledger.fromJSON}. Entries are ordered least-recently-used first, so a round trip
+ * preserves eviction order exactly. Pricing is configuration, not state, and is therefore
+ * re-supplied to `fromJSON` instead of being serialized.
+ */
+interface LedgerJSON {
+    /** The eviction cap the ledger was running with. */
+    readonly maxPrefixes: number;
+    /** Per-prefix aggregates, least-recently-used first. */
+    readonly entries: readonly LedgerEntryJSON[];
+}
+/**
+ * Bounded, LRU-evicting accumulator of {@link CacheUsage} records.
+ *
+ * Aggregation key: `usage.prefixKey` when the call executed a RACS plan, otherwise the
+ * synthetic `provider:model` pair, so plan-less calls still aggregate into ledger totals
+ * as {@link CacheUsage.prefixKey} documents.
+ *
+ * Hit-ratio definition: `readTokens / (readTokens + writeTokens + uncachedTokens)`, the
+ * share of all input-side token traffic that was served from cache. The denominator counts
+ * cached reads, cache writes of both TTL tiers, and uncached input, so a prefix that keeps
+ * paying write premiums without ever reading back scores zero, exactly the failure the
+ * ratio exists to expose. A zero denominator reports a ratio of zero. Uncached input
+ * derives from the all-in {@link CacheUsage.inputTokens} convention, see
+ * {@link Ledger.record}, so the denominator equals the all-in billed input when the
+ * source reports consistently.
+ *
+ * USD math, computed only for models the {@link PricingTable} covers:
+ * - `savedUsd = readTokens / 1e6 * (inputPerMTok - cacheReadPerMTok)`, what the cached
+ *   reads would have cost at base input price minus what they actually cost. Requires
+ *   `cacheReadPerMTok`, without it the model counts as not covered for savings.
+ * - `writeSpendUsd` is the write PREMIUM over base input price, not the full write bill:
+ *   `write5mTokens / 1e6 * (cacheWrite5mPerMTok - inputPerMTok)` plus the 1-hour tier
+ *   likewise. A mispriced table can make a tier premium negative, which would silently
+ *   inflate savings, so each tier term is clamped at zero before summing.
+ * - `netUsd = savedUsd - writeSpendUsd`, negative when caching lost money.
+ *
+ * Ledger-wide USD totals sum every prefix whose model the pricing table covers, prefixes
+ * without pricing contribute only token statistics, and the USD fields are omitted
+ * entirely when no aggregated prefix is covered.
+ */
+declare class Ledger {
+    private readonly pricing;
+    private readonly maxPrefixes;
+    /** Map iteration order doubles as recency order: oldest first, see {@link Ledger.record}. */
+    private readonly aggregates;
+    /**
+     * @param pricing - Per-model price cards for USD figures, always user-supplied. Without
+     *   it every token-denominated statistic is still reported, just no USD.
+     * @param maxPrefixes - Cap on distinct tracked prefixes before LRU eviction.
+     */
+    constructor(pricing?: PricingTable, maxPrefixes?: number);
+    /**
+     * Ingests one normalized usage record into the aggregate for its prefix.
+     *
+     * Per call, `uncachedTokens` accumulates
+     * `max(0, inputTokens - cacheReadTokens - cacheWriteTokens5m - cacheWriteTokens1h)`:
+     * {@link CacheUsage.inputTokens} is the ALL-IN billed input including cached reads and
+     * cache writes of both tiers, so the uncached remainder subtracts all three. Clamped at
+     * zero because a source reporting more cached traffic than billed input is a reporting
+     * artifact that must not drive the aggregate negative.
+     *
+     * @param usage - The normalized usage report, see {@link CacheUsage}.
+     * @returns `hit` is true when the call read at least one cached token. `evicted` names
+     *   the least-recently-used prefix key dropped to stay within `maxPrefixes`, present
+     *   only when an eviction happened.
+     */
+    record(usage: CacheUsage): {
+        hit: boolean;
+        evicted?: string;
+    };
+    /**
+     * Returns ledger-wide statistics with the per-prefix breakdown, optionally narrowed to
+     * one prefix key or one provider. The breakdown is sorted by prefix key ascending for
+     * stable, diffable output. USD presence rules are documented on {@link Ledger}.
+     *
+     * @param filter - Optional narrowing, both fields combine conjunctively when given.
+     */
+    stats(filter?: {
+        prefixKey?: string;
+        provider?: ProviderId;
+    }): LedgerStats;
+    /**
+     * Serializes every aggregate, least-recently-used first. The result is pure JSON data,
+     * carries no prompt content, and round-trips through {@link Ledger.fromJSON}.
+     */
+    toJSON(): LedgerJSON;
+    /**
+     * Rebuilds a ledger from {@link Ledger.toJSON} output, restoring aggregates and their
+     * recency order. Pricing is configuration, pass the current table, it is deliberately
+     * not part of the snapshot so stale prices never resurrect from persistence.
+     *
+     * @param json - A previously serialized ledger.
+     * @param pricing - The pricing table to compute USD figures with from now on.
+     */
+    static fromJSON(json: LedgerJSON, pricing?: PricingTable): Ledger;
+    /** Computes one {@link PrefixStats} from a live aggregate, USD rules per {@link Ledger}. */
+    private prefixStats;
+}
+
+/**
+ * The directive planner of RACS (Remote Agent Context Store).
+ *
+ * One pure class maps an analyzed prompt onto the cache-control surface of one provider
+ * family: explicit breakpoints, routing keys, server-side cache resources, or a reasoned
+ * no-op for passive providers. The planner is deterministic and stateless, it reads no
+ * clock and no random source, so identical inputs always yield identical directives. The
+ * engine core owns fingerprinting, drift tracking, refresh timing, and telemetry.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Aggregates the analysis stage computed once, so the planner never recounts the prompt.
+ */
+interface PlanAnalysis {
+    /** Findings the lint pass produced, context the planner extends through extraFindings. */
+    findings: LintFinding[];
+    /** Token count of the cacheable stable prefix, exact or estimated per segment rules. */
+    stableTokens: number;
+    /** Token count of the whole prompt, same exact-or-estimated provenance. */
+    totalTokens: number;
+    /**
+     * Count of leading segments, in request order, forming the left-anchored cacheable
+     * prefix. Prefix caches reuse nothing past this boundary on any provider family.
+     */
+    orderedStableBoundary: number;
+}
+/**
+ * The planner's contribution to one cache plan, merged by the engine core with the plan
+ * identity, the fingerprints, and the analysis findings.
+ */
+interface PlannerResult {
+    /** Provider-faithful instructions in application order. */
+    directives: CacheDirective[];
+    /** Cache economics, present when profile multipliers or pricing allow computing them. */
+    breakEven?: BreakEven;
+    /** One dense human-readable sentence per planning decision. */
+    reasoning: string;
+    /** Findings only the planning stage can detect, appended to the analysis findings. */
+    extraFindings: LintFinding[];
+}
+/**
+ * Maps one analyzed prompt to provider-faithful cache directives, per adapter family.
+ *
+ * Family semantics implemented here are research snapshots of June 2026, sources cited on
+ * the constants above, and every number flows from the {@link ProviderProfile}, so a
+ * profile override updates the planner without a release.
+ */
+declare class Planner {
+    /**
+     * Produces directives, break-even economics, and planner-stage findings for one input.
+     *
+     * @param input - The prompt being planned, segments in request order.
+     * @param profile - Effective provider profile, overrides already merged by the core.
+     * @param analysis - Aggregates the analysis stage computed, see {@link PlanAnalysis}.
+     * @param prefixKey - Deterministic key of the stable prefix, computed by the core.
+     * @param pricing - Optional model price card, refines multipliers and storage math.
+     * @param knownResource - Resource family only: whether the core already tracks a live
+     * cache resource for this prefix. First sight emits `'create'`, later sights `'reuse'`,
+     * and the core swaps `'reuse'` for `'refresh'` when its clock sits inside the last 10
+     * percent of the TTL window, the planner emits the shape, the core decides the timing.
+     */
+    plan(input: PlanInput, profile: ProviderProfile, analysis: PlanAnalysis, prefixKey: string, pricing?: Pricing, knownResource?: boolean): PlannerResult;
+    private planFamily;
+    /**
+     * Breakpoint family (anthropic, bedrock, hermes, microsoft-foundry): explicit markers,
+     * one TTL tier chosen from the declared reuse. The deepest stable boundary is always
+     * marked because the last marker determines left-anchored coverage, remaining budget
+     * goes to the largest stable spans by role weight. Economics follow the refresh-on-use
+     * model documented on {@link breakpointBreakEven} inside the TTL window and the
+     * touch-cost model on {@link keepWarmBreakEven} beyond it; when neither sustains the
+     * cache the planner declines with a reasoned `'none'` plus a `'write-premium-trap'`
+     * finding, so an emitted breakpoint plan is never knowingly unprofitable.
+     */
+    private planBreakpoint;
+    /**
+     * Routing-key family (openai, xai, mistral, moonshot, openrouter): the provider caches
+     * implicitly, the key only steers identical prefixes to the same cache shard, and the
+     * extended 24-hour retention tier rides along when supported and the reuse is sparse
+     * (OpenAI `prompt_cache_key` retention as of June 2026).
+     */
+    private planRoutingKey;
+    /**
+     * Resource family (google): the cache is a server resource the host creates, reuses,
+     * refreshes, and deletes, billed per token-hour of storage while it stays alive.
+     */
+    private planResource;
+    /**
+     * Passive family (groq, deepseek, ollama, lmstudio, huggingface, custom): no control
+     * surface exists, stable-first ordering and accounting are the whole contribution.
+     */
+    private planPassive;
+}
+
+/**
+ * Deterministic structural linting of a {@link PlanInput} segment list, the documented
+ * failure modes of production prefix caching caught before a single token is billed.
+ *
+ * Provider semantics this module leans on, researched June 2026:
+ * - Prefix caches are strictly left-anchored on every provider family, so one volatile
+ *   byte invalidates everything after it (Anthropic prompt caching docs, June 2026;
+ *   OpenAI prompt caching guide, June 2026).
+ * - Breakpoint providers hash tool definitions ahead of the message list, so a volatile
+ *   `'tools'` segment defeats the cache for the whole request (Anthropic `cache_control`
+ *   semantics, June 2026).
+ * - Prefixes below the provider minimum are silently uncached, no error, no usage signal
+ *   (1024 tokens on most Anthropic and OpenAI models as of June 2026); the minimum itself
+ *   always comes from the {@link ProviderProfile}, never from constants here.
+ *
+ * Privacy contract: content heuristics run only on segments that carry `content`.
+ * Hash-only segments (only `contentHash` present) are skipped by design, RACS never sees
+ * their text so there is nothing to scan. Finding messages never embed matched substrings,
+ * because findings travel inside persisted plans while segment content must never be
+ * persisted; matches are referenced by a short content digest instead, which still lets
+ * the owner locate the offending text in their own prompt source.
+ *
+ * Determinism: pure function of the input and profile, no clock, no randomness, findings
+ * are emitted in a fixed order (structural lints, then per-segment scans in segment order,
+ * then the prefix-level summary).
+ */
+
+/** Result of one {@link PrefixAnalyzer.analyze} pass, pure data. */
+interface PrefixAnalysis {
+    /** Lint findings in deterministic emission order. */
+    findings: LintFinding[];
+    /** Token total of the longest stable-or-semi run from the start, the cacheable prefix. */
+    stableTokens: number;
+    /** Token total of the whole prompt, exact or estimated per segment rules. */
+    totalTokens: number;
+    /** Index of the first volatile segment, `segments.length` when none is volatile. */
+    orderedStableBoundary: number;
+}
+/**
+ * Structural linter over a segment list and one provider profile. Stateless, every call
+ * is independent, safe to share one instance across plans.
+ */
+declare class PrefixAnalyzer {
+    /**
+     * Runs every structural lint and computes the prefix geometry the planner needs.
+     *
+     * @param input - The plan input whose segments are analyzed, in request order.
+     * @param profile - Effective provider profile, supplies `minCacheableTokens`.
+     * @returns Findings plus the cacheable-prefix token counts and the volatile boundary.
+     */
+    analyze(input: PlanInput, profile: ProviderProfile): PrefixAnalysis;
+    /** `'segment-order'`: the first volatile segment that precedes a cacheable one. */
+    private lintSegmentOrder;
+    /**
+     * `'volatile-early'`: a volatile segment inside the first half of total tokens and
+     * before any breakpoint-eligible boundary, the silent-cache-killer layout.
+     *
+     * A boundary is breakpoint-eligible only inside the leading stable run (a span that
+     * contains volatile content can never be read back), so eligibility reduces to the
+     * leading run reaching the provider minimum. The first volatile segment is reported, it
+     * is the one that caps the run. Its start offset equals `stableTokens` by construction.
+     */
+    private lintVolatileEarly;
+    /** Per-segment lints: declaration checks always, content heuristics only with content. */
+    private lintSegment;
+    /** `'timestamp-in-stable'`: timestamp-like content inside a stable or semi segment. */
+    private lintTimestamps;
+    /** `'identifier-in-stable'`: per-request identifier shapes inside a stable segment. */
+    private lintIdentifiers;
+    /** `'below-minimum'`: the stable prefix is silently uncacheable on this provider. */
+    private lintBelowMinimum;
+}
+
+/**
+ * Shipped provider profiles for RACS (Remote Agent Context Store), the numbers the planner
+ * reasons with.
+ *
+ * Every named provider is a thin parameterization of exactly one {@link AdapterFamily}, which
+ * is why one table covers the whole provider landscape without per-provider code paths. The
+ * values document provider semantics as researched in June 2026, each entry cites its source
+ * and retrieval date in JSDoc. Providers change terms faster than packages release, so every
+ * value is overridable per engine instance through {@link RACSOptions.profiles}, merged by
+ * {@link resolveProfile}.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The shipped profile table, one entry per {@link ProviderId}, semantics as documented in
+ * June 2026. Treat as read-only defaults: the planner must always go through
+ * {@link resolveProfile} so per-engine overrides apply.
+ */
+declare const PROVIDER_PROFILES: Readonly<Record<ProviderId, ProviderProfile>>;
+/**
+ * Returns the effective profile for one provider: the shipped table entry shallow-merged
+ * with the caller's per-engine override from {@link RACSOptions.profiles}.
+ *
+ * Merge rules:
+ * - Shallow: every override field replaces the shipped field wholesale, `ttls` included.
+ * - Override fields holding `undefined` at runtime (possible for untyped JavaScript
+ *   callers) are ignored rather than clobbering shipped values.
+ * - `id` is not overridable, the result always names the requested provider.
+ *
+ * @param id - Provider whose profile to resolve.
+ * @param overrides - Per-provider override map, see {@link RACSOptions.profiles}.
+ * @returns The merged profile the planner actually uses.
+ * @throws RacsError code `'ERR_INVALID_INPUT'` when `id` names no shipped profile (only
+ * reachable from untyped callers) or when the merged `family` is not a known
+ * {@link AdapterFamily}.
+ */
+declare function resolveProfile(id: ProviderId, overrides?: RACSOptions['profiles']): ProviderProfile;
+
+/**
+ * Key-value state backend of RACS (Remote Agent Context Store): one JSON string under one
+ * key in any structural {@link KvLike} store, the persistence shape for edge runtimes and
+ * multi-instance hosts that already run Redis, Upstash, or Cloudflare KV.
+ *
+ * RACS never constructs the client and never sees connection credentials, the host passes
+ * a ready object, per the product invariant.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Creates a state backend persisting snapshots as one JSON string in a key-value store.
+ *
+ * Any client exposing string get, set, and delete wraps into {@link KvLike} in one line,
+ * no adapter package needed:
+ *
+ * @example
+ * ```ts
+ * // Redis (node-redis or ioredis):
+ * const state = kvState({
+ *   get: (k) => redis.get(k),
+ *   set: (k, v) => redis.set(k, v),
+ *   delete: (k) => redis.del(k),
+ * });
+ *
+ * // Upstash Redis:
+ * const state = kvState({
+ *   get: (k) => upstash.get<string>(k),
+ *   set: (k, v) => upstash.set(k, v),
+ *   delete: (k) => upstash.del(k),
+ * });
+ *
+ * // Cloudflare KV (a binding named RACS_KV):
+ * const state = kvState({
+ *   get: (k) => env.RACS_KV.get(k),
+ *   set: (k, v) => env.RACS_KV.put(k, v),
+ *   delete: (k) => env.RACS_KV.delete(k),
+ * });
+ * ```
+ *
+ * Load tolerates both `null` and `undefined` from `get`, the two absence conventions in
+ * the wild, and returns `undefined` for either, the normal first-run case. A present but
+ * unparseable value throws RacsError `'ERR_STATE_LOAD'`, and a parseable value with the
+ * wrong snapshot version throws RacsError `'ERR_STATE_VERSION'`.
+ *
+ * @param kv - The ready client, see {@link KvLike}.
+ * @param key - Storage key for the snapshot, namespace it per engine when several engines
+ *   share one store.
+ */
+declare function kvState(kv: KvLike, key?: string): StateBackend;
+
+/**
+ * In-memory state backend of RACS (Remote Agent Context Store): the zero-config default
+ * persistence shape, a snapshot held in a closure variable. Nothing survives the process,
+ * which is exactly right for tests, demos, and hosts that persist elsewhere.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Creates a state backend that keeps the latest snapshot in memory.
+ *
+ * Each call returns an independent backend with its own closure variable, two engines
+ * given two `memoryState()` results never see each other's snapshots. The snapshot object
+ * is stored by reference, callers must treat saved snapshots as immutable, which the
+ * {@link StateSnapshot} readonly contract already requires.
+ *
+ * @returns A {@link StateBackend} whose `load` resolves to the last saved snapshot, or
+ *   `undefined` before the first save.
+ */
+declare function memoryState(): StateBackend;
+
+/**
+ * Deterministic, non-cryptographic hashing primitives for RACS (Remote Agent Context
+ * Store): prefix keys, combined keys, and seeded short identifiers.
+ *
+ * Everything here is pure, allocation-light, dependency-free, and runs identically in
+ * browsers, edge runtimes, workers, and Node. No randomness, no clock, no platform globals.
+ *
+ * Security stance: FNV-1a is NOT a cryptographic hash. It is trivially invertible and
+ * collision-constructible by an adversary, so values produced by this module must never
+ * gate a security decision (authentication, authorization, integrity verification). They
+ * exist solely to give byte-equal inputs equal keys for cache bookkeeping.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Hashes `text` with FNV-1a 64-bit over its UTF-16 code units (two bytes per code unit,
+ * low byte first) and returns the digest as a fixed-width 16-character lowercase hex
+ * string.
+ *
+ * Determinism: pure function of the input, identical across runtimes and runs.
+ *
+ * Collision odds, non-adversarial inputs: with a 64-bit digest the birthday bound puts the
+ * probability of any collision among n distinct inputs at roughly n^2 / 2^65, about 1 in
+ * 37 million for one million distinct prefixes, reaching 50 percent only near 5 billion
+ * inputs. Acceptable for cache-key bookkeeping, where a collision costs at worst one
+ * misattributed statistic, never a wrong answer to the host.
+ *
+ * Non-cryptographic: an adversary can construct collisions at will. Never use the result
+ * for security decisions, see the module-level security stance.
+ *
+ * @param text - The string to hash, hashed as-is with no normalization.
+ * @returns 16 lowercase hex characters, zero-padded, for example '0a1b2c3d4e5f6789'.
+ */
+declare function fnv1a64(text: string): string;
+/**
+ * Derives one key from several parts by joining them with a separator that cannot appear
+ * in hex output (U+001F) and hashing the joined string with {@link fnv1a64}.
+ *
+ * The separator guarantees that part boundaries contribute to the digest, so
+ * `combineKeys(['ab', 'c'])` and `combineKeys(['a', 'bc'])` differ even though their
+ * concatenations are equal. Used to fuse segment hashes, provider, model, and agent
+ * identity into one prefix key.
+ *
+ * Same non-cryptographic caveats and collision odds as {@link fnv1a64}.
+ *
+ * @param parts - Key components in significance order, empty parts are preserved.
+ * @returns 16 lowercase hex characters identifying the part sequence.
+ */
+declare function combineKeys(parts: readonly string[]): string;
+
+/**
+ * Token estimation helpers for RACS (Remote Agent Context Store).
+ *
+ * Estimates exist to gate minimum-token planning decisions (is this prefix long enough to
+ * cache at all, does the write premium pay back), never to bill anyone. Exact counts come
+ * from provider usage reports recorded after the fact, and callers with a real tokenizer
+ * should pass explicit token counts, which always win, see {@link tokensOf}.
+ *
+ * Pure module: no dependencies, no randomness, no clock, runs everywhere.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Estimates the token count of `content` as the ceiling of its UTF-16 length divided by
+ * 4, the industry characters-per-token heuristic (see {@link CHARS_PER_TOKEN}).
+ *
+ * Accuracy contract: this is a planning estimate, not a measurement. It is typically
+ * within tens of percent for English prose and can be off by more for CJK text or dense
+ * code. Exact counts come from provider usage reports; estimates only gate minimum-token
+ * planning such as the `'below-minimum'` lint and break-even math. Pass exact counts from
+ * a provider tokenizer whenever precision matters.
+ *
+ * @param content - The text to estimate, measured by UTF-16 length, no normalization.
+ * @returns Non-negative integer estimate, 0 for the empty string.
+ */
+declare function estimateTokens(content: string): number;
+
+export { BreakEven, CacheDirective, CacheUsage, KvLike, Ledger, type LedgerEntryJSON, type LedgerJSON, LedgerStats, LintFinding, PROVIDER_PROFILES, type PlanAnalysis, PlanInput, Planner, type PlannerResult, type PrefixAnalysis, PrefixAnalyzer, Pricing, PricingTable, ProviderId, ProviderProfile, RACS, RACSOptions, RacsError, StateBackend, combineKeys, createRACS, estimateTokens, fnv1a64, kvState, memoryState, resolveProfile };