@takk/racs 1.0.0

package/dist/index.js

@@ -0,0 +1,2057 @@
+// src/drift/Fingerprints.ts
+var Fingerprints = class _Fingerprints {
+  capacity;
+  /** Map iteration order doubles as recency order, oldest lineage first. */
+  records = /* @__PURE__ */ new Map();
+  /**
+   * @param capacity - Cap on distinct tracked lineages before LRU eviction.
+   */
+  constructor(capacity = 1e3) {
+    this.capacity = capacity;
+  }
+  /**
+   * Records the fingerprint of one plan and compares it with the previous plan of the same
+   * lineage.
+   *
+   * @param input - The plan input, provides the lineage key and segment stabilities.
+   * @param prefixKey - Deterministic prefix key the plan produced.
+   * @param segmentHashes - Segment id to content hash, as the planner derived them.
+   * @param totalTokens - Token count of the stable prefix behind `prefixKey`. Stored, and
+   *   reported as `invalidatedTokens` if a later plan drifts to a different key, because
+   *   those are exactly the previously cached tokens the drift killed.
+   * @param now - Milliseconds since the Unix epoch, from the injected engine clock.
+   * @returns `undefined` on the first observation of a lineage and when nothing relevant
+   *   changed. Otherwise a {@link DriftReport} naming the changed, added, or removed
+   *   stable and semi segments, with `invalidatedTokens` equal to the previous stable
+   *   prefix size when the prefix key changed, and zero when the key survived.
+   */
+  observe(input, prefixKey, segmentHashes, totalTokens, now) {
+    const key = input.agentId ?? `${input.provider}:${input.model}`;
+    const stabilityOf = /* @__PURE__ */ new Map();
+    for (const segment of input.segments) {
+      stabilityOf.set(segment.id, segment.stability);
+    }
+    const next = /* @__PURE__ */ new Map();
+    for (const [id, hash] of segmentHashes) {
+      next.set(id, { hash, stability: stabilityOf.get(id) ?? "volatile" });
+    }
+    const previous = this.records.get(key);
+    this.records.delete(key);
+    this.records.set(key, { prefixKey, tokens: totalTokens, segments: next });
+    if (this.records.size > this.capacity) {
+      const oldest = this.records.keys().next();
+      if (!oldest.done) {
+        this.records.delete(oldest.value);
+      }
+    }
+    if (previous === void 0) {
+      return void 0;
+    }
+    const changed = /* @__PURE__ */ new Set();
+    for (const [id, fingerprint] of next) {
+      if (fingerprint.stability === "volatile") {
+        continue;
+      }
+      const before = previous.segments.get(id);
+      if (before === void 0 || before.hash !== fingerprint.hash) {
+        changed.add(id);
+      }
+    }
+    for (const [id, fingerprint] of previous.segments) {
+      if (!next.has(id) && fingerprint.stability !== "volatile") {
+        changed.add(id);
+      }
+    }
+    if (changed.size === 0 && prefixKey === previous.prefixKey) {
+      return void 0;
+    }
+    return {
+      ...input.agentId !== void 0 ? { agentId: input.agentId } : {},
+      prefixKey,
+      previousKey: previous.prefixKey,
+      changedSegmentIds: [...changed].sort(),
+      invalidatedTokens: prefixKey === previous.prefixKey ? 0 : previous.tokens,
+      timestamp: now
+    };
+  }
+  /**
+   * Removes every lineage record whose latest prefix key satisfies `predicate` and returns
+   * the distinct prefix keys removed. Engine-level invalidation calls this when the host
+   * clears prefixes, for example on credential rotation: a removed lineage simply restarts
+   * drift tracking at its next plan, and first observations never report drift.
+   */
+  prune(predicate) {
+    const removed = /* @__PURE__ */ new Set();
+    for (const [key, record] of [...this.records]) {
+      if (predicate(record.prefixKey)) {
+        this.records.delete(key);
+        removed.add(record.prefixKey);
+      }
+    }
+    return [...removed];
+  }
+  /**
+   * Serializes every lineage record, least-recently-observed first. Pure JSON data, no
+   * prompt content, round-trips through {@link Fingerprints.fromJSON}.
+   */
+  toJSON() {
+    const entries = [];
+    for (const [key, record] of this.records) {
+      const segments = [];
+      for (const [id, fingerprint] of record.segments) {
+        segments.push({ id, hash: fingerprint.hash, stability: fingerprint.stability });
+      }
+      entries.push({ key, prefixKey: record.prefixKey, tokens: record.tokens, segments });
+    }
+    return { capacity: this.capacity, entries };
+  }
+  /**
+   * Rebuilds a fingerprint store from {@link Fingerprints.toJSON} output, restoring
+   * lineage records, their segment maps, and their recency order.
+   *
+   * @param json - A previously serialized store.
+   */
+  static fromJSON(json) {
+    const store = new _Fingerprints(json.capacity);
+    for (const entry of json.entries) {
+      const segments = /* @__PURE__ */ new Map();
+      for (const segment of entry.segments) {
+        segments.set(segment.id, { hash: segment.hash, stability: segment.stability });
+      }
+      store.records.set(entry.key, {
+        prefixKey: entry.prefixKey,
+        tokens: entry.tokens,
+        segments
+      });
+    }
+    return store;
+  }
+};
+
+// src/errors.ts
+var RacsError = 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.
+   */
+  code;
+  /**
+   * @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, code) {
+    super(message);
+    this.name = "RacsError";
+    this.code = code;
+  }
+  /**
+   * 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) {
+    return new _RacsError(message, "ERR_INVALID_INPUT");
+  }
+};
+
+// src/ledger/Ledger.ts
+var Ledger = class _Ledger {
+  pricing;
+  maxPrefixes;
+  /** Map iteration order doubles as recency order: oldest first, see {@link Ledger.record}. */
+  aggregates = /* @__PURE__ */ new Map();
+  /**
+   * @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, maxPrefixes = 1e3) {
+    this.pricing = pricing;
+    this.maxPrefixes = maxPrefixes;
+  }
+  /**
+   * 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) {
+    const key = usage.prefixKey ?? `${usage.provider}:${usage.model}`;
+    const aggregate = this.aggregates.get(key) ?? {
+      provider: usage.provider,
+      model: usage.model,
+      calls: 0,
+      readTokens: 0,
+      write5mTokens: 0,
+      write1hTokens: 0,
+      uncachedTokens: 0
+    };
+    this.aggregates.delete(key);
+    this.aggregates.set(key, aggregate);
+    aggregate.calls += 1;
+    aggregate.readTokens += usage.cacheReadTokens;
+    aggregate.write5mTokens += usage.cacheWriteTokens5m ?? 0;
+    aggregate.write1hTokens += usage.cacheWriteTokens1h ?? 0;
+    aggregate.uncachedTokens += Math.max(
+      0,
+      usage.inputTokens - usage.cacheReadTokens - (usage.cacheWriteTokens5m ?? 0) - (usage.cacheWriteTokens1h ?? 0)
+    );
+    aggregate.provider = usage.provider;
+    aggregate.model = usage.model;
+    const hit = usage.cacheReadTokens > 0;
+    let evicted;
+    if (this.aggregates.size > this.maxPrefixes) {
+      const oldest = this.aggregates.keys().next();
+      if (!oldest.done) {
+        evicted = oldest.value;
+        this.aggregates.delete(oldest.value);
+      }
+    }
+    return evicted === void 0 ? { hit } : { hit, evicted };
+  }
+  /**
+   * 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) {
+    const prefixes = [];
+    let calls = 0;
+    let readTokens = 0;
+    let writeTokens = 0;
+    let uncachedTokens = 0;
+    let savedUsd = 0;
+    let writeSpendUsd = 0;
+    let priced = false;
+    for (const [key, aggregate] of this.aggregates) {
+      if (filter?.prefixKey !== void 0 && key !== filter.prefixKey) {
+        continue;
+      }
+      if (filter?.provider !== void 0 && aggregate.provider !== filter.provider) {
+        continue;
+      }
+      const stat = this.prefixStats(key, aggregate);
+      prefixes.push(stat);
+      calls += aggregate.calls;
+      readTokens += aggregate.readTokens;
+      writeTokens += aggregate.write5mTokens + aggregate.write1hTokens;
+      uncachedTokens += aggregate.uncachedTokens;
+      if (stat.savedUsd !== void 0) {
+        savedUsd += stat.savedUsd;
+        priced = true;
+      }
+      if (stat.writeSpendUsd !== void 0) {
+        writeSpendUsd += stat.writeSpendUsd;
+        priced = true;
+      }
+    }
+    prefixes.sort((a, b) => a.prefixKey < b.prefixKey ? -1 : a.prefixKey > b.prefixKey ? 1 : 0);
+    const denominator = readTokens + writeTokens + uncachedTokens;
+    return {
+      calls,
+      hitRatio: denominator === 0 ? 0 : readTokens / denominator,
+      readTokens,
+      writeTokens,
+      uncachedTokens,
+      ...priced ? { savedUsd, netUsd: savedUsd - writeSpendUsd } : {},
+      prefixes
+    };
+  }
+  /**
+   * 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() {
+    const entries = [];
+    for (const [key, aggregate] of this.aggregates) {
+      entries.push({
+        key,
+        provider: aggregate.provider,
+        model: aggregate.model,
+        calls: aggregate.calls,
+        readTokens: aggregate.readTokens,
+        write5mTokens: aggregate.write5mTokens,
+        write1hTokens: aggregate.write1hTokens,
+        uncachedTokens: aggregate.uncachedTokens
+      });
+    }
+    return { maxPrefixes: this.maxPrefixes, entries };
+  }
+  /**
+   * 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, pricing) {
+    const ledger = new _Ledger(pricing, json.maxPrefixes);
+    for (const entry of json.entries) {
+      ledger.aggregates.set(entry.key, {
+        provider: entry.provider,
+        model: entry.model,
+        calls: entry.calls,
+        readTokens: entry.readTokens,
+        write5mTokens: entry.write5mTokens,
+        write1hTokens: entry.write1hTokens,
+        uncachedTokens: entry.uncachedTokens
+      });
+    }
+    return ledger;
+  }
+  /** Computes one {@link PrefixStats} from a live aggregate, USD rules per {@link Ledger}. */
+  prefixStats(key, aggregate) {
+    const writeTokens = aggregate.write5mTokens + aggregate.write1hTokens;
+    const denominator = aggregate.readTokens + writeTokens + aggregate.uncachedTokens;
+    const hitRatio = denominator === 0 ? 0 : aggregate.readTokens / denominator;
+    const price = this.pricing?.[aggregate.model];
+    let savedUsd;
+    let writeSpendUsd;
+    if (price !== void 0) {
+      if (price.cacheReadPerMTok !== void 0) {
+        savedUsd = aggregate.readTokens / 1e6 * (price.inputPerMTok - price.cacheReadPerMTok);
+      }
+      const premium5m = price.cacheWrite5mPerMTok === void 0 ? 0 : Math.max(
+        0,
+        aggregate.write5mTokens / 1e6 * (price.cacheWrite5mPerMTok - price.inputPerMTok)
+      );
+      const premium1h = price.cacheWrite1hPerMTok === void 0 ? 0 : Math.max(
+        0,
+        aggregate.write1hTokens / 1e6 * (price.cacheWrite1hPerMTok - price.inputPerMTok)
+      );
+      writeSpendUsd = premium5m + premium1h;
+    }
+    return {
+      prefixKey: key,
+      calls: aggregate.calls,
+      hitRatio,
+      readTokens: aggregate.readTokens,
+      writeTokens,
+      uncachedTokens: aggregate.uncachedTokens,
+      ...savedUsd !== void 0 ? { savedUsd } : {},
+      ...writeSpendUsd !== void 0 ? { writeSpendUsd } : {}
+    };
+  }
+};
+
+// src/stats/hash.ts
+var FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
+var FNV_PRIME = 0x100000001b3n;
+var MASK_64 = 0xffffffffffffffffn;
+var KEY_SEPARATOR = "";
+function fnv1a64Value(text) {
+  let hash = FNV_OFFSET_BASIS;
+  for (let index = 0; index < text.length; index += 1) {
+    const unit = text.charCodeAt(index);
+    hash ^= BigInt(unit & 255);
+    hash = hash * FNV_PRIME & MASK_64;
+    hash ^= BigInt(unit >>> 8);
+    hash = hash * FNV_PRIME & MASK_64;
+  }
+  return hash;
+}
+function fnv1a64(text) {
+  return fnv1a64Value(text).toString(16).padStart(16, "0");
+}
+function combineKeys(parts) {
+  return fnv1a64(parts.join(KEY_SEPARATOR));
+}
+function shortId(seededCounter, salt) {
+  return fnv1a64Value(`${salt}${KEY_SEPARATOR}${String(seededCounter)}`).toString(36);
+}
+
+// src/stats/tokens.ts
+var CHARS_PER_TOKEN = 4;
+function estimateTokens(content) {
+  return Math.ceil(content.length / CHARS_PER_TOKEN);
+}
+function tokensOf(segment) {
+  if (typeof segment.tokens === "number") {
+    return segment.tokens;
+  }
+  if (typeof segment.content === "string") {
+    return estimateTokens(segment.content);
+  }
+  return 0;
+}
+
+// src/plan/Planner.ts
+var ROLE_WEIGHT = {
+  tools: 4,
+  system: 3,
+  documents: 2,
+  history: 1,
+  dynamic: 0
+};
+var TTL_SECONDS = { "5m": 300, "1h": 3600 };
+var FIVE_MINUTE_INTERVAL_CEILING = 240;
+var ONE_HOUR_INTERVAL_CEILING = 3300;
+var RESOURCE_TTL_MIN_SECONDS = 300;
+var RESOURCE_TTL_DEFAULT_SECONDS = 3600;
+var formatCount = (value) => Number.isInteger(value) ? value.toString() : value.toFixed(2);
+var formatUsd = (value) => `${value.toPrecision(3)} USD`;
+var intervalSecondsOf = (input) => {
+  const reuse = input.reuse;
+  if (reuse === void 0) {
+    return void 0;
+  }
+  if (reuse.intervalSeconds !== void 0) {
+    return reuse.intervalSeconds;
+  }
+  if (reuse.callsPerHour !== void 0 && reuse.callsPerHour > 0) {
+    return 3600 / reuse.callsPerHour;
+  }
+  return void 0;
+};
+var callsPerHourOf = (input) => {
+  const reuse = input.reuse;
+  if (reuse === void 0) {
+    return void 0;
+  }
+  if (reuse.intervalSeconds !== void 0 && reuse.intervalSeconds > 0) {
+    return 3600 / reuse.intervalSeconds;
+  }
+  if (reuse.callsPerHour !== void 0) {
+    return reuse.callsPerHour;
+  }
+  return void 0;
+};
+var writeMultiplierFor = (ttl, profile, pricing) => {
+  const fromProfile = ttl === "1h" ? profile.writeMultiplier1h : profile.writeMultiplier5m;
+  if (fromProfile !== void 0) {
+    return fromProfile;
+  }
+  if (pricing !== void 0 && pricing.inputPerMTok > 0) {
+    const writePrice = ttl === "1h" ? pricing.cacheWrite1hPerMTok : pricing.cacheWrite5mPerMTok;
+    if (writePrice !== void 0) {
+      return writePrice / pricing.inputPerMTok;
+    }
+  }
+  return void 0;
+};
+var readMultiplierFor = (profile, pricing) => {
+  if (profile.readMultiplier !== void 0) {
+    return profile.readMultiplier;
+  }
+  if (pricing !== void 0 && pricing.inputPerMTok > 0 && pricing.cacheReadPerMTok !== void 0) {
+    return pricing.cacheReadPerMTok / pricing.inputPerMTok;
+  }
+  return void 0;
+};
+var stableSpansOf = (segments, boundary) => {
+  const spans = [];
+  let open;
+  const limit = Math.min(boundary, segments.length);
+  for (let index = 0; index < limit; index += 1) {
+    const segment = segments[index];
+    if (segment === void 0 || segment.stability === "volatile") {
+      break;
+    }
+    const tokens = tokensOf(segment);
+    if (open !== void 0 && open.role === segment.role) {
+      open = {
+        role: open.role,
+        tokens: open.tokens + tokens,
+        endSegmentId: segment.id,
+        endIndex: index
+      };
+    } else {
+      if (open !== void 0) {
+        spans.push(open);
+      }
+      open = { role: segment.role, tokens, endSegmentId: segment.id, endIndex: index };
+    }
+  }
+  if (open !== void 0) {
+    spans.push(open);
+  }
+  return spans;
+};
+var breakpointBreakEven = (coveredTokens, ttl, callsPerHour, profile, pricing) => {
+  const writeMultiplier = writeMultiplierFor(ttl, profile, pricing);
+  const readMultiplier = readMultiplierFor(profile, pricing);
+  if (writeMultiplier === void 0 || readMultiplier === void 0) {
+    return void 0;
+  }
+  const writePremiumTokens = Math.max(0, coveredTokens * (writeMultiplier - 1));
+  const savingsPerReuse = coveredTokens * (1 - readMultiplier);
+  const minReusesToProfit = savingsPerReuse > 0 ? Math.ceil(writePremiumTokens / savingsPerReuse) : Number.POSITIVE_INFINITY;
+  if (callsPerHour === void 0) {
+    const profitable2 = 1 >= minReusesToProfit;
+    const reasoning2 = `The ${ttl} write multiplier ${formatCount(writeMultiplier)} prices the premium at ${formatCount(writePremiumTokens)} base-token equivalents, each reuse at read multiplier ${formatCount(readMultiplier)} recovers ${formatCount(savingsPerReuse)}, so ${formatCount(minReusesToProfit)} reuse(s) repay the write against the single assumed reuse (no reuse pattern was declared; multipliers are price-relative, the math holds with or without a pricing table), ${profitable2 ? "profitable" : "not profitable"}.`;
+    return { writePremiumTokens, minReusesToProfit, profitable: profitable2, reasoning: reasoning2 };
+  }
+  const expectedReuses = Math.max(1, Math.round(callsPerHour));
+  const profitable = Number.isFinite(minReusesToProfit);
+  const reasoning = `The ${ttl} write multiplier ${formatCount(writeMultiplier)} prices the premium at ${formatCount(writePremiumTokens)} base-token equivalents, each reuse at read multiplier ${formatCount(readMultiplier)} recovers ${formatCount(savingsPerReuse)}, so ${formatCount(minReusesToProfit)} reuse(s) repay the single write; reads refresh the ${ttl} window at no extra cost (refresh-on-use), steady declared reuse keeps the entry alive indefinitely at about ${formatCount(expectedReuses)} reuse(s) per hour (multipliers are price-relative, the math holds with or without a pricing table), ${profitable ? "profitable" : "not profitable"}.`;
+  return { writePremiumTokens, minReusesToProfit, profitable, reasoning };
+};
+var keepWarmBreakEven = (coveredTokens, ttl, callsPerHour, refreshesPerHour, readMultiplier, profile, pricing) => {
+  const writeMultiplier = writeMultiplierFor(ttl, profile, pricing);
+  if (writeMultiplier === void 0 || callsPerHour <= 0) {
+    return void 0;
+  }
+  const writePremiumTokens = Math.max(0, coveredTokens * (writeMultiplier - 1));
+  const savingsPerReuse = coveredTokens * (1 - readMultiplier);
+  const touchCostPerReuse = refreshesPerHour / callsPerHour * coveredTokens * readMultiplier;
+  const netPerReuse = savingsPerReuse - touchCostPerReuse;
+  const profitable = netPerReuse > 0;
+  const minReusesToProfit = profitable ? Math.ceil(writePremiumTokens / netPerReuse) : Number.POSITIVE_INFINITY;
+  const reasoning = `Keep-warm economics: each reuse recovers ${formatCount(savingsPerReuse)} base-token equivalents and carries ${formatCount(touchCostPerReuse)} of scheduled refresh touches (${formatCount(refreshesPerHour)} touch(es) per hour at read multiplier ${formatCount(readMultiplier)} spread over ${formatCount(callsPerHour)} call(s) per hour), netting ${formatCount(netPerReuse)}, so the single ${ttl} write premium of ${formatCount(writePremiumTokens)} is repaid after ${formatCount(minReusesToProfit)} reuse(s), ${profitable ? "profitable" : "not profitable"}.`;
+  return { writePremiumTokens, minReusesToProfit, profitable, reasoning };
+};
+var resourceBreakEven = (stableTokens, callsPerHour, profile, pricing) => {
+  const storagePerMTokHour = pricing?.storagePerMTokHour ?? profile.storagePerMTokHour;
+  if (storagePerMTokHour === void 0 || pricing === void 0 || pricing.inputPerMTok <= 0) {
+    return void 0;
+  }
+  const readPerMTok = pricing.cacheReadPerMTok ?? (profile.readMultiplier === void 0 ? void 0 : pricing.inputPerMTok * profile.readMultiplier);
+  if (readPerMTok === void 0) {
+    return void 0;
+  }
+  const savingsPerCallUsd = stableTokens / 1e6 * (pricing.inputPerMTok - readPerMTok);
+  if (savingsPerCallUsd <= 0) {
+    return void 0;
+  }
+  const storagePerHourUsd = stableTokens / 1e6 * storagePerMTokHour;
+  const writePremiumTokens = storagePerHourUsd / pricing.inputPerMTok * 1e6;
+  const minReusesToProfit = Math.ceil(storagePerHourUsd / savingsPerCallUsd);
+  const profitable = callsPerHour >= minReusesToProfit;
+  const reasoning = `Keeping ${formatCount(stableTokens)} tokens resident bills ${formatUsd(storagePerHourUsd)} per hour of storage (${formatCount(writePremiumTokens)} base-token equivalents), each cached read saves ${formatUsd(savingsPerCallUsd)}, so ${formatCount(minReusesToProfit)} reuse(s) per hour break even against ${formatCount(callsPerHour)} expected, ${profitable ? "profitable" : "not profitable"}.`;
+  return { writePremiumTokens, minReusesToProfit, profitable, reasoning };
+};
+var Planner = class {
+  /**
+   * 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, profile, analysis, prefixKey, pricing, knownResource = false) {
+    const result = this.planFamily(input, profile, analysis, prefixKey, pricing, knownResource);
+    if (profile.notes !== void 0 && profile.notes !== "") {
+      return { ...result, reasoning: `${result.reasoning} Provider note: ${profile.notes}` };
+    }
+    return result;
+  }
+  planFamily(input, profile, analysis, prefixKey, pricing, knownResource) {
+    switch (profile.family) {
+      case "breakpoint":
+        return this.planBreakpoint(input, profile, analysis, pricing);
+      case "routing-key":
+        return this.planRoutingKey(input, profile, analysis, prefixKey);
+      case "resource":
+        return this.planResource(input, profile, analysis, prefixKey, knownResource, pricing);
+      default:
+        return this.planPassive(profile);
+    }
+  }
+  /**
+   * 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.
+   */
+  planBreakpoint(input, profile, analysis, pricing) {
+    const extraFindings = [];
+    const minCacheable = profile.minCacheableTokens ?? 0;
+    if (analysis.stableTokens < minCacheable) {
+      return {
+        directives: [
+          {
+            kind: "none",
+            reason: `stable prefix is ${formatCount(analysis.stableTokens)} tokens, below the provider minimum of ${formatCount(minCacheable)}, the provider would silently cache nothing`
+          }
+        ],
+        reasoning: `Skipped caching because the ${formatCount(analysis.stableTokens)}-token stable prefix sits below the ${formatCount(minCacheable)}-token provider minimum, a marker there would buy nothing.`,
+        extraFindings
+      };
+    }
+    const spans = stableSpansOf(input.segments, analysis.orderedStableBoundary);
+    const deepest = spans[spans.length - 1];
+    if (deepest === void 0) {
+      const first = input.segments[0];
+      if (first !== void 0 && first.stability === "volatile") {
+        extraFindings.push({
+          severity: "error",
+          code: "breakpoint-after-volatile",
+          segmentId: first.id,
+          message: `the only breakpoint candidate follows volatile segment '${first.id}', a span written there could never be read back; move volatile content after the stable prefix`
+        });
+        return {
+          directives: [
+            {
+              kind: "none",
+              reason: "every breakpoint candidate sits after a volatile segment, a written span could never be read back"
+            }
+          ],
+          reasoning: "Refused to place a breakpoint after a volatile segment, the written span could never be read back, so the write premium would be pure loss.",
+          extraFindings
+        };
+      }
+      return {
+        directives: [
+          { kind: "none", reason: "no left-anchored stable prefix exists to mark for caching" }
+        ],
+        reasoning: "Skipped caching, the prompt carries no left-anchored stable prefix to mark.",
+        extraFindings
+      };
+    }
+    const budget = profile.maxBreakpoints ?? 1;
+    if (budget <= 0) {
+      return {
+        directives: [
+          { kind: "none", reason: "the provider profile allows zero cache breakpoints" }
+        ],
+        reasoning: "Skipped caching, the effective profile grants no breakpoint slots.",
+        extraFindings
+      };
+    }
+    const sentences = [];
+    const interval = intervalSecondsOf(input);
+    const callsPerHour = callsPerHourOf(input);
+    const tiers = profile.ttls ?? ["5m"];
+    const supports1h = tiers.includes("1h");
+    let ttl;
+    let keepWarm;
+    if (interval === void 0) {
+      ttl = tiers.includes("5m") || !supports1h ? "5m" : "1h";
+      sentences.push(
+        `No reuse pattern was declared, defaulting to the ${ttl} tier, the lowest write premium the profile offers, with a single assumed reuse for break-even.`
+      );
+    } else if (interval <= FIVE_MINUTE_INTERVAL_CEILING && tiers.includes("5m")) {
+      ttl = "5m";
+      sentences.push(
+        `Reuse every ${formatCount(interval)}s fits the 5m tier with ${formatCount(TTL_SECONDS["5m"] - interval)}s of refresh headroom before the 300s window closes, and every read refreshes the window at no cost.`
+      );
+    } else if (interval <= ONE_HOUR_INTERVAL_CEILING && supports1h) {
+      ttl = "1h";
+      sentences.push(
+        `Reuse every ${formatCount(interval)}s overruns the 5m tier, the 1h tier holds it with ${formatCount(TTL_SECONDS["1h"] - interval)}s of refresh headroom under the 3600s window, and every read refreshes the window at no cost.`
+      );
+    } else {
+      const widest = supports1h ? "1h" : "5m";
+      const refreshesPerHour = 3600 / TTL_SECONDS[widest];
+      const readMultiplier = readMultiplierFor(profile, pricing);
+      if (callsPerHour === void 0 || readMultiplier === void 0 || readMultiplier >= 1 || callsPerHour * (1 - readMultiplier) <= refreshesPerHour * readMultiplier) {
+        extraFindings.push({
+          severity: "warning",
+          code: "write-premium-trap",
+          message: `the declared reuse every ${formatCount(interval)}s outruns the widest ${widest} window and the traffic cannot cover keep-warm touches, so the write premium on ${formatCount(analysis.stableTokens)} stable tokens would never be repaid; raise reuse density or skip caching`
+        });
+        return {
+          directives: [
+            {
+              kind: "none",
+              reason: "reuse interval exceeds provider TTL, caching would re-write every call"
+            }
+          ],
+          reasoning: `Reuse every ${formatCount(interval)}s exceeds what the widest ${widest} window holds with refresh headroom, every call would pay the write premium again, so no marker is placed.`,
+          extraFindings
+        };
+      }
+      ttl = widest;
+      keepWarm = { refreshesPerHour, readMultiplier };
+      sentences.push(
+        `Reuse every ${formatCount(interval)}s exceeds the ${widest} window, but ${formatCount(callsPerHour)} calls per hour against ${formatCount(refreshesPerHour)} keep-warm touches per hour at read multiplier ${formatCount(readMultiplier)} keep refresh-keeping profitable, so the ${widest} tier stays on with touches scheduled at 90 percent of the TTL.`
+      );
+    }
+    const ranked = [...spans.slice(0, -1)].sort((a, b) => {
+      const byWeight = ROLE_WEIGHT[b.role] - ROLE_WEIGHT[a.role];
+      if (byWeight !== 0) {
+        return byWeight;
+      }
+      if (b.tokens !== a.tokens) {
+        return b.tokens - a.tokens;
+      }
+      return a.endIndex - b.endIndex;
+    });
+    const chosen = [deepest, ...ranked.slice(0, Math.max(0, budget - 1))].sort(
+      (a, b) => a.endIndex - b.endIndex
+    );
+    const directives = chosen.map((span) => ({
+      kind: "breakpoint",
+      segmentId: span.endSegmentId,
+      ttl
+    }));
+    const lastChosen = chosen[chosen.length - 1] ?? deepest;
+    let coveredTokens = 0;
+    for (const span of spans) {
+      if (span.endIndex <= lastChosen.endIndex) {
+        coveredTokens += span.tokens;
+      }
+    }
+    const placement = chosen.map(
+      (span) => `${span.role} ending at '${span.endSegmentId}', ${formatCount(span.tokens)} tokens`
+    ).join("; ");
+    sentences.push(
+      `Placed ${formatCount(directives.length)} of ${formatCount(budget)} allowed breakpoints: the deepest stable boundary '${deepest.endSegmentId}' is always marked because the last marker determines left-anchored coverage, and the remaining slots go to the largest stable spans weighted tools over system over documents over history (${placement}) because the provider hashes tools, then system, then messages, so each extra marker preserves partial reuse when a later region drifts, covering ${formatCount(coveredTokens)} of ${formatCount(analysis.totalTokens)} prompt tokens.`
+    );
+    const breakEven = keepWarm !== void 0 && callsPerHour !== void 0 ? keepWarmBreakEven(
+      coveredTokens,
+      ttl,
+      callsPerHour,
+      keepWarm.refreshesPerHour,
+      keepWarm.readMultiplier,
+      profile,
+      pricing
+    ) : breakpointBreakEven(
+      coveredTokens,
+      ttl,
+      interval === void 0 ? void 0 : callsPerHour,
+      profile,
+      pricing
+    );
+    if (breakEven !== void 0) {
+      sentences.push(breakEven.reasoning);
+      if (!breakEven.profitable) {
+        extraFindings.push({
+          severity: "warning",
+          code: "write-premium-trap",
+          message: `expected reuse inside the ${ttl} window does not repay the cache write premium on ${formatCount(coveredTokens)} covered stable tokens; raise reuse density, choose a longer TTL tier, or skip caching`
+        });
+      }
+    }
+    return {
+      directives,
+      ...breakEven !== void 0 ? { breakEven } : {},
+      reasoning: sentences.join(" "),
+      extraFindings
+    };
+  }
+  /**
+   * 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).
+   */
+  planRoutingKey(input, profile, analysis, prefixKey) {
+    const interval = intervalSecondsOf(input);
+    const wantsRetention = profile.supportsRetention === true && interval !== void 0 && interval > 3600;
+    const directives = [
+      {
+        kind: "routing-key",
+        key: prefixKey,
+        ...wantsRetention ? { retention: "24h" } : {}
+      }
+    ];
+    const retentionNote = wantsRetention && interval !== void 0 ? `, and reuse every ${formatCount(interval)}s outlives the default cache window, so the 24h retention tier is requested behind the key` : "";
+    return {
+      directives,
+      reasoning: `${profile.id} caches prefixes automatically on the server, the routing key only pins the ${formatCount(analysis.stableTokens)}-token stable prefix of ${formatCount(analysis.totalTokens)} prompt tokens to one cache shard, so keeping that prefix byte-stable is the real lever${retentionNote}.`,
+      extraFindings: []
+    };
+  }
+  /**
+   * 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.
+   */
+  planResource(input, profile, analysis, prefixKey, knownResource, pricing) {
+    const extraFindings = [];
+    const interval = intervalSecondsOf(input);
+    const ttlSeconds = interval === void 0 ? RESOURCE_TTL_DEFAULT_SECONDS : Math.min(RESOURCE_TTL_DEFAULT_SECONDS, Math.max(RESOURCE_TTL_MIN_SECONDS, interval * 4));
+    const resourceKey = prefixKey !== "" ? prefixKey : combineKeys([input.provider, input.model, input.agentId ?? ""]);
+    const callsPerHour = callsPerHourOf(input) ?? 1;
+    const breakEven = resourceBreakEven(analysis.stableTokens, callsPerHour, profile, pricing);
+    if (callsPerHour < 1) {
+      extraFindings.push({
+        severity: "warning",
+        code: "write-premium-trap",
+        message: `the storage trap: at ${formatCount(callsPerHour)} reuses per hour, per-token-hour storage on ${formatCount(analysis.stableTokens)} resident tokens outruns the read savings; raise reuse density or rely on implicit provider caching`
+      });
+      return {
+        directives: [
+          {
+            kind: "none",
+            reason: "below one reuse per hour the per-token-hour storage bill outruns the read savings, the storage trap, so no cache resource is worth keeping alive"
+          }
+        ],
+        ...breakEven !== void 0 ? { breakEven } : {},
+        reasoning: `Skipped the cache resource because ${formatCount(callsPerHour)} reuses per hour cannot cover storage billed for every hour the resource stays alive, the classic resource-family storage trap.`,
+        extraFindings
+      };
+    }
+    const action = knownResource ? "reuse" : "create";
+    const directives = [{ kind: "resource", action, resourceKey, ttlSeconds }];
+    const sentences = [
+      `${action === "create" ? "Creating" : "Reusing"} the server-side cache resource for this prefix with a ${formatCount(ttlSeconds)}s TTL, four times the ${interval === void 0 ? "default-assumed" : `${formatCount(interval)}s`} reuse interval clamped to [${formatCount(RESOURCE_TTL_MIN_SECONDS)}, ${formatCount(RESOURCE_TTL_DEFAULT_SECONDS)}], and the core swaps reuse for refresh inside the last 10 percent of that window.`
+    ];
+    if (breakEven !== void 0) {
+      sentences.push(breakEven.reasoning);
+      if (!breakEven.profitable) {
+        extraFindings.push({
+          severity: "warning",
+          code: "write-premium-trap",
+          message: `at ${formatCount(callsPerHour)} reuses per hour the per-token-hour storage bill on ${formatCount(analysis.stableTokens)} resident tokens exceeds the read savings; raise reuse density or shorten the resource TTL`
+        });
+      }
+    }
+    return {
+      directives,
+      ...breakEven !== void 0 ? { breakEven } : {},
+      reasoning: sentences.join(" "),
+      extraFindings
+    };
+  }
+  /**
+   * Passive family (groq, deepseek, ollama, lmstudio, huggingface, custom): no control
+   * surface exists, stable-first ordering and accounting are the whole contribution.
+   */
+  planPassive(profile) {
+    return {
+      directives: [
+        {
+          kind: "none",
+          reason: "provider caches automatically (or exposes no controls); RACS contributes structure linting and analytics"
+        }
+      ],
+      reasoning: `${profile.id} exposes no cache control surface, so stable-first segment ordering is the entire optimization, and the ledger still accounts every cached token the provider reports.`,
+      extraFindings: []
+    };
+  }
+};
+
+// src/plan/PrefixAnalyzer.ts
+var ISO_8601_DATETIME = /\b\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:?\d{2})?\b/;
+var UNIX_EPOCH = /\b(?:\d{13}|\d{10})\b/;
+var RELATIVE_TIME_NEAR_DIGITS = /\b(?:today|current time)\b[^0-9\n\r]{0,32}[0-9]|[0-9][^0-9\n\r]{0,32}\b(?:today|current time)\b/i;
+var UUID_V4 = /\b[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/i;
+var HEX_RUN = /\b[0-9a-f]{24,}\b/i;
+var BASE64_RUN = /[A-Za-z0-9+/]{24,}={0,2}/g;
+var digestOf = (match) => fnv1a64(match).slice(0, 8);
+var firstMatch = (pattern, content) => {
+  const result = pattern.exec(content);
+  return result ? result[0] : void 0;
+};
+var PrefixAnalyzer = class {
+  /**
+   * 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, profile) {
+    const segments = input.segments;
+    let totalTokens = 0;
+    let orderedStableBoundary = segments.length;
+    let stableTokens = 0;
+    for (const [index, segment] of segments.entries()) {
+      const tokens = tokensOf(segment);
+      totalTokens += tokens;
+      if (index < orderedStableBoundary) {
+        if (segment.stability === "volatile") {
+          orderedStableBoundary = index;
+        } else {
+          stableTokens += tokens;
+        }
+      }
+    }
+    const findings = [];
+    this.lintSegmentOrder(segments, orderedStableBoundary, findings);
+    this.lintVolatileEarly(
+      segments,
+      orderedStableBoundary,
+      stableTokens,
+      totalTokens,
+      profile,
+      findings
+    );
+    for (const segment of segments) {
+      this.lintSegment(segment, findings);
+    }
+    this.lintBelowMinimum(stableTokens, profile, findings);
+    return { findings, stableTokens, totalTokens, orderedStableBoundary };
+  }
+  /** `'segment-order'`: the first volatile segment that precedes a cacheable one. */
+  lintSegmentOrder(segments, orderedStableBoundary, findings) {
+    const volatileSegment = segments[orderedStableBoundary];
+    if (volatileSegment === void 0) {
+      return;
+    }
+    for (let index = orderedStableBoundary + 1; index < segments.length; index += 1) {
+      const later = segments[index];
+      if (later !== void 0 && later.stability !== "volatile") {
+        findings.push({
+          severity: "warning",
+          code: "segment-order",
+          segmentId: volatileSegment.id,
+          message: `Volatile segment '${volatileSegment.id}' precedes ${later.stability} segment '${later.id}'. Prefix caches are left-anchored, so every token after '${volatileSegment.id}' is unreachable for the cache. Reorder stable-first: move '${later.id}' and every other stable segment ahead of '${volatileSegment.id}'.`
+        });
+        return;
+      }
+    }
+  }
+  /**
+   * `'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.
+   */
+  lintVolatileEarly(segments, orderedStableBoundary, stableTokens, totalTokens, profile, findings) {
+    const volatileSegment = segments[orderedStableBoundary];
+    if (volatileSegment === void 0 || totalTokens === 0) {
+      return;
+    }
+    const minimumEligible = profile.minCacheableTokens !== void 0 && profile.minCacheableTokens > 0 ? profile.minCacheableTokens : 1;
+    const inFirstHalf = stableTokens * 2 < totalTokens;
+    if (inFirstHalf && stableTokens < minimumEligible) {
+      findings.push({
+        severity: "error",
+        code: "volatile-early",
+        segmentId: volatileSegment.id,
+        message: `Volatile segment '${volatileSegment.id}' sits inside the first half of the prompt (${stableTokens} of ${totalTokens} tokens precede it) and before any breakpoint-eligible boundary (provider minimum ${minimumEligible} tokens on '${profile.id}'). Nothing in this prompt can ever be cached. The usual culprits are timestamps or session metadata interpolated into the system prompt; move every per-call value to the end of the prompt and keep the opening segments byte-stable.`
+      });
+    }
+  }
+  /** Per-segment lints: declaration checks always, content heuristics only with content. */
+  lintSegment(segment, findings) {
+    if (segment.role === "tools" && segment.stability === "volatile") {
+      findings.push({
+        severity: "error",
+        code: "unstable-tools",
+        segmentId: segment.id,
+        message: `Tools segment '${segment.id}' is declared volatile. Breakpoint providers hash tool definitions first, so volatile tools defeat the cache for the entire request. Tool instability is almost always a serialization bug, fix key ordering or remove timestamps from descriptions, then declare the segment stable.`
+      });
+    }
+    if (segment.role === "dynamic" && segment.stability === "stable") {
+      findings.push({
+        severity: "info",
+        code: "missing-stability",
+        segmentId: segment.id,
+        message: `Segment '${segment.id}' has the dynamic role but is declared stable. Dynamic content is expected to differ on every call, which contradicts the declaration. Declare it volatile, or change the role if the content really is byte-stable.`
+      });
+    }
+    const content = segment.content;
+    if (typeof content !== "string") {
+      return;
+    }
+    if (segment.stability === "stable" || segment.stability === "semi") {
+      this.lintTimestamps(segment, content, findings);
+    }
+    if (segment.stability === "stable") {
+      this.lintIdentifiers(segment, content, findings);
+    }
+  }
+  /** `'timestamp-in-stable'`: timestamp-like content inside a stable or semi segment. */
+  lintTimestamps(segment, content, findings) {
+    const hits = [];
+    const iso = firstMatch(ISO_8601_DATETIME, content);
+    if (iso !== void 0) {
+      hits.push(`an ISO-8601 datetime (digest ${digestOf(iso)})`);
+    }
+    const epoch = firstMatch(UNIX_EPOCH, content);
+    if (epoch !== void 0) {
+      hits.push(`a 10-or-13-digit unix epoch (digest ${digestOf(epoch)})`);
+    }
+    if (RELATIVE_TIME_NEAR_DIGITS.test(content)) {
+      hits.push(`the words 'today' or 'current time' near digits`);
+    }
+    if (hits.length === 0) {
+      return;
+    }
+    findings.push({
+      severity: "warning",
+      code: "timestamp-in-stable",
+      segmentId: segment.id,
+      message: `Segment '${segment.id}' is declared ${segment.stability} but contains ${hits.join(", and ")}. A timestamp changes the prefix on every call and silently defeats the cache. Move live time values into a volatile segment at the prompt tail.`
+    });
+  }
+  /** `'identifier-in-stable'`: per-request identifier shapes inside a stable segment. */
+  lintIdentifiers(segment, content, findings) {
+    let kind;
+    let match = firstMatch(UUID_V4, content);
+    if (match !== void 0) {
+      kind = "a UUID v4-like identifier";
+    } else {
+      match = firstMatch(HEX_RUN, content);
+      if (match !== void 0) {
+        kind = "a hex run of 24 or more characters";
+      } else {
+        for (const candidate of content.matchAll(BASE64_RUN)) {
+          const text = candidate[0];
+          if (text !== void 0 && /\d/.test(text) && /[a-z]/i.test(text)) {
+            match = text;
+            kind = "a base64-like run of 24 or more characters";
+            break;
+          }
+        }
+      }
+    }
+    if (match === void 0 || kind === void 0) {
+      return;
+    }
+    findings.push({
+      severity: "warning",
+      code: "identifier-in-stable",
+      segmentId: segment.id,
+      message: `Segment '${segment.id}' is declared stable but contains ${kind} (digest ${digestOf(match)}). Session ids and request ids churn per call, the same failure mode as a timestamp. Move per-request identifiers into a volatile segment.`
+    });
+  }
+  /** `'below-minimum'`: the stable prefix is silently uncacheable on this provider. */
+  lintBelowMinimum(stableTokens, profile, findings) {
+    const minimum = profile.minCacheableTokens;
+    if (minimum === void 0 || minimum <= 0 || stableTokens >= minimum) {
+      return;
+    }
+    findings.push({
+      severity: "info",
+      code: "below-minimum",
+      message: `The stable prefix totals ${stableTokens} tokens, below the ${minimum}-token minimum '${profile.id}' will cache. The provider would silently cache nothing. Lengthen the stable prefix, or accept that this prompt rides uncached on this provider.`
+    });
+  }
+};
+
+// src/providers/profiles.ts
+var ADAPTER_FAMILIES = [
+  "breakpoint",
+  "routing-key",
+  "resource",
+  "passive"
+];
+var PROVIDER_PROFILES = {
+  /**
+   * Anthropic Claude API, explicit `cache_control` breakpoints with two TTL tiers.
+   *
+   * Writes cost 1.25x base input on the 5-minute tier and 2x on the 1-hour tier, cached
+   * reads cost 0.1x, at most 4 breakpoints per request. The 1024-token minimum is the
+   * conservative common case: the newest frontier models cache from 512 tokens and the
+   * small models require 4096, override per model through {@link RACSOptions.profiles}
+   * when targeting those.
+   *
+   * Source: Anthropic prompt caching documentation,
+   * https://docs.claude.com/en/docs/build-with-claude/prompt-caching, retrieved June 2026.
+   */
+  anthropic: {
+    id: "anthropic",
+    family: "breakpoint",
+    minCacheableTokens: 1024,
+    maxBreakpoints: 4,
+    ttls: ["5m", "1h"],
+    writeMultiplier5m: 1.25,
+    writeMultiplier1h: 2,
+    readMultiplier: 0.1,
+    notes: "Explicit cache_control breakpoints, up to 4 per request, 5m and 1h TTL tiers. Minimum cacheable prefix is 1024 tokens in the common case, 512 on the newest frontier models, 4096 on small models, override per model via options.profiles."
+  },
+  /**
+   * OpenAI, automatic server-side prefix caching steered by `prompt_cache_key`.
+   *
+   * Caches in 128-token increments above a 1024-token minimum, no write counter and no
+   * write premium. The cached-read discount varies between 50 and 90 percent by model, so
+   * the 0.25 read multiplier is a conservative default, override per model when the exact
+   * discount is known. Extended 24-hour retention attaches to `prompt_cache_key`, hence
+   * `supportsRetention`.
+   *
+   * Source: OpenAI prompt caching guide,
+   * https://platform.openai.com/docs/guides/prompt-caching, retrieved June 2026.
+   */
+  openai: {
+    id: "openai",
+    family: "routing-key",
+    minCacheableTokens: 1024,
+    readMultiplier: 0.25,
+    supportsRetention: true,
+    notes: "Automatic prefix caching in 128-token increments above 1024 tokens, prompt_cache_key routing, no write counter, read discount varies 50 to 90 percent by model so 0.25 is a conservative default."
+  },
+  /**
+   * Google Gemini, implicit caching on 2.5 and newer models plus the explicit
+   * `cachedContents` resource lifecycle with caller-set TTL and per-token-hour storage
+   * billing at 1.0 USD per million tokens per hour.
+   *
+   * Source: Google Gemini API context caching documentation,
+   * https://ai.google.dev/gemini-api/docs/caching, retrieved June 2026.
+   */
+  google: {
+    id: "google",
+    family: "resource",
+    minCacheableTokens: 2048,
+    readMultiplier: 0.1,
+    storagePerMTokHour: 1,
+    notes: "Implicit caching on 2.5+ models plus explicit cachedContents lifecycle with TTL and per-token-hour storage billing."
+  },
+  /**
+   * Amazon Bedrock, `cachePoint` blocks on the Converse API, Anthropic-equivalent
+   * breakpoint semantics and multipliers.
+   *
+   * Source: Amazon Bedrock prompt caching documentation,
+   * https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html, retrieved
+   * June 2026.
+   */
+  bedrock: {
+    id: "bedrock",
+    family: "breakpoint",
+    minCacheableTokens: 1024,
+    maxBreakpoints: 4,
+    ttls: ["5m", "1h"],
+    writeMultiplier5m: 1.25,
+    writeMultiplier1h: 2,
+    readMultiplier: 0.1,
+    notes: "cachePoint blocks on the Converse API, Anthropic-equivalent breakpoint semantics."
+  },
+  /**
+   * xAI Grok, automatic prefix caching, steerable with the `x-grok-conv-id` header and
+   * `prompt_cache_key`, cached reads at roughly 0.16x base input.
+   *
+   * Source: xAI API documentation, https://docs.x.ai/, retrieved June 2026.
+   */
+  xai: {
+    id: "xai",
+    family: "routing-key",
+    minCacheableTokens: 1024,
+    readMultiplier: 0.16,
+    notes: "Automatic prefix caching, steerable via the x-grok-conv-id header and prompt_cache_key."
+  },
+  /**
+   * Groq, automatic prefix caching on gpt-oss models with no control surface, cached reads
+   * at 0.5x base input, entries expire after roughly 2 hours idle.
+   *
+   * Source: Groq prompt caching documentation,
+   * https://console.groq.com/docs/prompt-caching, retrieved June 2026.
+   */
+  groq: {
+    id: "groq",
+    family: "passive",
+    minCacheableTokens: 128,
+    readMultiplier: 0.5,
+    notes: "Automatic on gpt-oss models, no controls, entries expire after 2 hours idle."
+  },
+  /**
+   * DeepSeek, disk-based automatic context caching with cache hit and miss token
+   * reporting, cached reads at 0.1x base input.
+   *
+   * Source: DeepSeek context caching documentation,
+   * https://api-docs.deepseek.com/guides/kv_cache, retrieved June 2026.
+   */
+  deepseek: {
+    id: "deepseek",
+    family: "passive",
+    readMultiplier: 0.1,
+    notes: "Disk-based automatic context caching with hit and miss token reporting."
+  },
+  /**
+   * Mistral, automatic caching in 64-token blocks with `prompt_cache_key` routing, cached
+   * reads at 0.1x base input.
+   *
+   * Source: Mistral platform documentation, https://docs.mistral.ai/, retrieved June 2026.
+   */
+  mistral: {
+    id: "mistral",
+    family: "routing-key",
+    minCacheableTokens: 64,
+    readMultiplier: 0.1,
+    notes: "64-token cache blocks, prompt_cache_key routing."
+  },
+  /**
+   * OpenRouter normalizes `cache_control` passthrough and `cached_tokens` reporting across
+   * upstream providers. The numbers are conservative defaults because the effective
+   * discount is whatever the routed upstream charges.
+   *
+   * Source: OpenRouter prompt caching documentation,
+   * https://openrouter.ai/docs/features/prompt-caching, retrieved June 2026.
+   */
+  openrouter: {
+    id: "openrouter",
+    family: "routing-key",
+    minCacheableTokens: 1024,
+    readMultiplier: 0.25,
+    notes: "Normalizes cache_control passthrough and cached_tokens reporting across upstreams, effective discount depends on the routed upstream."
+  },
+  /**
+   * Moonshot Kimi, platform caching reached through the OpenAI-compatible surface. The
+   * public semantics are less documented than peers as of June 2026, so the profile
+   * carries conservative defaults mirroring the OpenAI numbers.
+   *
+   * Source: Moonshot platform documentation, https://platform.moonshot.ai/docs, retrieved
+   * June 2026.
+   */
+  moonshot: {
+    id: "moonshot",
+    family: "routing-key",
+    minCacheableTokens: 1024,
+    readMultiplier: 0.25,
+    notes: "Kimi platform caching via the OpenAI-compatible surface, semantics less documented, conservative defaults."
+  },
+  /**
+   * Ollama, local runtime KV reuse with no billing dimension, analytics measure
+   * latency-motivated reuse only.
+   *
+   * Source: Ollama documentation, https://docs.ollama.com/, retrieved June 2026.
+   */
+  ollama: {
+    id: "ollama",
+    family: "passive",
+    notes: "Local runtime KV reuse, no billing, analytics measure latency-motivated reuse only."
+  },
+  /**
+   * LM Studio, local runtime KV reuse with no billing dimension, same posture as Ollama.
+   *
+   * Source: LM Studio documentation, https://lmstudio.ai/docs, retrieved June 2026.
+   */
+  lmstudio: {
+    id: "lmstudio",
+    family: "passive",
+    notes: "Local runtime KV reuse, no billing, analytics measure latency-motivated reuse only."
+  },
+  /**
+   * Hugging Face Inference Endpoints expose no public prefix-cache controls as of
+   * June 2026, so the profile is passive and carries no numbers.
+   *
+   * Source: Hugging Face Inference Endpoints documentation,
+   * https://huggingface.co/docs/inference-endpoints, retrieved June 2026.
+   */
+  huggingface: {
+    id: "huggingface",
+    family: "passive",
+    notes: "Inference Endpoints without public prefix-cache controls as of June 2026."
+  },
+  /**
+   * Claude models on Microsoft Foundry honor `cache_control` unchanged, so the profile
+   * mirrors the Anthropic numbers.
+   *
+   * Source: Microsoft Foundry documentation for Anthropic Claude models,
+   * https://learn.microsoft.com/en-us/azure/ai-foundry/, retrieved June 2026.
+   */
+  "microsoft-foundry": {
+    id: "microsoft-foundry",
+    family: "breakpoint",
+    minCacheableTokens: 1024,
+    maxBreakpoints: 4,
+    ttls: ["5m", "1h"],
+    writeMultiplier5m: 1.25,
+    writeMultiplier1h: 2,
+    readMultiplier: 0.1,
+    notes: "Claude on Microsoft Foundry honors cache_control, Anthropic breakpoint semantics."
+  },
+  /**
+   * Nous Research Hermes Agent rides Anthropic `cache_control` semantics with its fixed
+   * system_and_3 layout, the system prompt plus the last 3 messages, so the multipliers,
+   * the 1024-token cacheable minimum, and the breakpoint budget are the Anthropic numbers
+   * and RACS plans superior layouts for it.
+   *
+   * Sources: Hermes Agent system_and_3 cache layout, observed June 2026, and Anthropic
+   * prompt caching documentation,
+   * https://docs.claude.com/en/docs/build-with-claude/prompt-caching, retrieved June 2026.
+   */
+  hermes: {
+    id: "hermes",
+    family: "breakpoint",
+    minCacheableTokens: 1024,
+    maxBreakpoints: 4,
+    ttls: ["5m", "1h"],
+    writeMultiplier5m: 1.25,
+    writeMultiplier1h: 2,
+    readMultiplier: 0.1,
+    notes: "Hermes Agent system_and_3 layout (system plus last 3 messages) rides Anthropic cache_control semantics, RACS plans superior layouts for it."
+  },
+  /**
+   * Escape hatch for providers RACS does not name yet, fully caller-defined through
+   * {@link RACSOptions.profiles}. Defaults to passive so a bare 'custom' plan still orders
+   * segments, lints, and accounts usage without inventing numbers.
+   */
+  custom: {
+    id: "custom",
+    family: "passive",
+    notes: "Fully caller-defined via the options.profiles override."
+  }
+};
+function resolveProfile(id, overrides) {
+  const base = PROVIDER_PROFILES[id];
+  if (base === void 0) {
+    throw RacsError.invalid(
+      `Unknown provider id '${String(id)}', expected one of: ${Object.keys(PROVIDER_PROFILES).join(", ")}.`
+    );
+  }
+  const override = overrides?.[id];
+  if (override === void 0) {
+    return base;
+  }
+  const merged = {
+    ...base,
+    ...override.family !== void 0 ? { family: override.family } : {},
+    ...override.minCacheableTokens !== void 0 ? { minCacheableTokens: override.minCacheableTokens } : {},
+    ...override.maxBreakpoints !== void 0 ? { maxBreakpoints: override.maxBreakpoints } : {},
+    ...override.ttls !== void 0 ? { ttls: override.ttls } : {},
+    ...override.writeMultiplier5m !== void 0 ? { writeMultiplier5m: override.writeMultiplier5m } : {},
+    ...override.writeMultiplier1h !== void 0 ? { writeMultiplier1h: override.writeMultiplier1h } : {},
+    ...override.readMultiplier !== void 0 ? { readMultiplier: override.readMultiplier } : {},
+    ...override.supportsRetention !== void 0 ? { supportsRetention: override.supportsRetention } : {},
+    ...override.storagePerMTokHour !== void 0 ? { storagePerMTokHour: override.storagePerMTokHour } : {},
+    ...override.notes !== void 0 ? { notes: override.notes } : {},
+    id: base.id
+  };
+  if (!ADAPTER_FAMILIES.includes(merged.family)) {
+    throw RacsError.invalid(
+      `Profile override for '${id}' sets family '${String(merged.family)}', expected one of: ${ADAPTER_FAMILIES.join(", ")}.`
+    );
+  }
+  return merged;
+}
+
+// src/schedule/TtlKeeper.ts
+var REFRESH_FRACTION = 0.9;
+function ttlToMillis(ttl) {
+  if (ttl === "5m") {
+    return 3e5;
+  }
+  if (ttl === "1h") {
+    return 36e5;
+  }
+  return ttl * 1e3;
+}
+var TtlKeeper = class _TtlKeeper {
+  capacity;
+  /** Map iteration order doubles as recency order, oldest entry first. */
+  entries = /* @__PURE__ */ new Map();
+  /**
+   * @param capacity - Cap on distinct tracked prefixes before LRU eviction.
+   */
+  constructor(capacity = 1e3) {
+    this.capacity = capacity;
+  }
+  /**
+   * Records or replaces the keep-warm entry for the plan's prefix.
+   *
+   * `refreshAt = lastWriteAt + 0.9 * ttlMillis`, see {@link REFRESH_FRACTION} for why
+   * 90 percent.
+   *
+   * @param plan - The plan whose directives describe the cache writes to keep warm.
+   * @param now - Milliseconds since the Unix epoch, from the injected engine clock,
+   *   taken as the moment of the cache write.
+   */
+  track(plan, now) {
+    let ttl;
+    for (const directive of plan.directives) {
+      if (directive.kind === "breakpoint") {
+        if (ttl === void 0 || ttlToMillis(directive.ttl) < ttlToMillis(ttl)) {
+          ttl = directive.ttl;
+        }
+      } else if (directive.kind === "resource") {
+        if (directive.action === "delete") {
+          this.remove(plan.prefixKey);
+          return;
+        }
+        if (ttl === void 0 || ttlToMillis(directive.ttlSeconds) < ttlToMillis(ttl)) {
+          ttl = directive.ttlSeconds;
+        }
+      }
+    }
+    if (ttl === void 0) {
+      return;
+    }
+    const entry = {
+      prefixKey: plan.prefixKey,
+      provider: plan.provider,
+      model: plan.model,
+      ttl,
+      lastWriteAt: now,
+      refreshAt: now + REFRESH_FRACTION * ttlToMillis(ttl)
+    };
+    this.entries.delete(plan.prefixKey);
+    this.entries.set(plan.prefixKey, entry);
+    if (this.entries.size > this.capacity) {
+      const oldest = this.entries.keys().next();
+      if (!oldest.done) {
+        this.entries.delete(oldest.value);
+      }
+    }
+  }
+  /**
+   * Returns every entry whose refresh touch is due at or before `now`, most overdue first,
+   * ties broken by prefix key for deterministic output. Read-only: the host performs the
+   * warming call and then reports it through {@link TtlKeeper.markRefreshed}.
+   *
+   * @param now - Milliseconds since the Unix epoch, from the injected engine clock.
+   */
+  due(now) {
+    const due = [];
+    for (const entry of this.entries.values()) {
+      if (entry.refreshAt <= now) {
+        due.push(entry);
+      }
+    }
+    due.sort(
+      (a, b) => a.refreshAt === b.refreshAt ? a.prefixKey < b.prefixKey ? -1 : a.prefixKey > b.prefixKey ? 1 : 0 : a.refreshAt - b.refreshAt
+    );
+    return due;
+  }
+  /**
+   * Slides the TTL window after the host touched the cache: `lastWriteAt` becomes `now`
+   * and `refreshAt` moves to 90 percent of the entry's TTL after it. Unknown prefixes are
+   * ignored, the host may legitimately refresh a prefix the keeper already evicted.
+   *
+   * @param prefixKey - The prefix the host kept warm.
+   * @param now - Milliseconds since the Unix epoch of the touch.
+   */
+  markRefreshed(prefixKey, now) {
+    const entry = this.entries.get(prefixKey);
+    if (entry === void 0) {
+      return;
+    }
+    const updated = {
+      ...entry,
+      lastWriteAt: now,
+      refreshAt: now + REFRESH_FRACTION * ttlToMillis(entry.ttl)
+    };
+    this.entries.delete(prefixKey);
+    this.entries.set(prefixKey, updated);
+  }
+  /**
+   * Drops the entry for a prefix, used when the host abandons a cache or a resource
+   * directive deletes it. Unknown prefixes are ignored.
+   */
+  remove(prefixKey) {
+    this.entries.delete(prefixKey);
+  }
+  /**
+   * Serializes every entry, least-recently-tracked first. Pure JSON data, round-trips
+   * through {@link TtlKeeper.fromJSON}.
+   */
+  toJSON() {
+    return { capacity: this.capacity, entries: [...this.entries.values()] };
+  }
+  /**
+   * Rebuilds a keeper from {@link TtlKeeper.toJSON} output, restoring entries and their
+   * recency order.
+   *
+   * @param json - A previously serialized keeper.
+   */
+  static fromJSON(json) {
+    const keeper = new _TtlKeeper(json.capacity);
+    for (const entry of json.entries) {
+      keeper.entries.set(entry.prefixKey, entry);
+    }
+    return keeper;
+  }
+};
+
+// src/core/createRACS.ts
+var DEFAULT_SEED = 7;
+var DEFAULT_MAX_PREFIXES = 1e3;
+var DRIFT_RING_CAPACITY = 200;
+var RESOURCE_REFRESH_FRACTION = 0.9;
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isResourceRecordJSON(value) {
+  return isRecord(value) && typeof value.key === "string" && typeof value.provider === "string" && typeof value.ttlSeconds === "number" && typeof value.lastWriteAt === "number";
+}
+function isDriftReport(value) {
+  return isRecord(value) && (value.agentId === void 0 || typeof value.agentId === "string") && typeof value.prefixKey === "string" && typeof value.previousKey === "string" && Array.isArray(value.changedSegmentIds) && value.changedSegmentIds.every((id) => typeof id === "string") && typeof value.invalidatedTokens === "number" && typeof value.timestamp === "number";
+}
+function requireCount(value, field) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw RacsError.invalid(
+      `${field} must be a finite non-negative number, received ${String(value)}.`
+    );
+  }
+}
+function validatePlanInput(input) {
+  if (!isRecord(input)) {
+    throw RacsError.invalid(`PlanInput must be an object, received ${typeof input}.`);
+  }
+  if (typeof input.model !== "string" || input.model === "") {
+    throw RacsError.invalid("PlanInput.model must be a non-empty model identifier string.");
+  }
+  if (!Array.isArray(input.segments) || input.segments.length === 0) {
+    throw RacsError.invalid("PlanInput.segments must be a non-empty array of prompt segments.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const segment of input.segments) {
+    if (typeof segment.id !== "string" || segment.id === "") {
+      throw RacsError.invalid("Every segment needs a non-empty string id unique within the plan.");
+    }
+    if (seen.has(segment.id)) {
+      throw RacsError.invalid(
+        `Segment id '${segment.id}' appears more than once, ids must be unique within one plan.`
+      );
+    }
+    seen.add(segment.id);
+    if (typeof segment.content !== "string" && (typeof segment.contentHash !== "string" || segment.contentHash === "")) {
+      throw RacsError.invalid(
+        `Segment '${segment.id}' carries neither content nor contentHash, provide at least one so the segment can be keyed.`
+      );
+    }
+    if (segment.tokens !== void 0) {
+      requireCount(segment.tokens, `Segment '${segment.id}' tokens`);
+    }
+  }
+}
+function validateUsage(usage) {
+  if (!isRecord(usage)) {
+    throw RacsError.invalid(`CacheUsage must be an object, received ${typeof usage}.`);
+  }
+  const provider = usage.provider;
+  if (typeof provider !== "string" || provider === "") {
+    throw RacsError.invalid("CacheUsage.provider must be a non-empty provider id string.");
+  }
+  if (typeof usage.model !== "string" || usage.model === "") {
+    throw RacsError.invalid("CacheUsage.model must be a non-empty model identifier string.");
+  }
+  requireCount(usage.inputTokens, "CacheUsage.inputTokens");
+  requireCount(usage.cacheReadTokens, "CacheUsage.cacheReadTokens");
+  if (usage.cacheWriteTokens5m !== void 0) {
+    requireCount(usage.cacheWriteTokens5m, "CacheUsage.cacheWriteTokens5m");
+  }
+  if (usage.cacheWriteTokens1h !== void 0) {
+    requireCount(usage.cacheWriteTokens1h, "CacheUsage.cacheWriteTokens1h");
+  }
+  if (usage.timestamp !== void 0) {
+    requireCount(usage.timestamp, "CacheUsage.timestamp");
+  }
+}
+function hashOf(segment) {
+  if (typeof segment.contentHash === "string" && segment.contentHash !== "") {
+    return segment.contentHash;
+  }
+  return fnv1a64(segment.content ?? "");
+}
+var RacsEngine = class {
+  profiles;
+  pricing;
+  maxPrefixes;
+  clock;
+  salt;
+  state;
+  analyzer = new PrefixAnalyzer();
+  planner = new Planner();
+  /** Replaced wholesale when a persisted section restores, hence not readonly. */
+  ledger;
+  fingerprints;
+  keeper;
+  /** Live resource-family caches by resource key, the planner's `knownResource` source. */
+  resources = /* @__PURE__ */ new Map();
+  /** Chronological drift ring, oldest first, newest last, capacity {@link DRIFT_RING_CAPACITY}. */
+  driftRing = [];
+  /**
+   * Every prefix key registered for keeper and resource bookkeeping, capped at
+   * maxPrefixes, each mapped to its provider so {@link RACS.invalidate} can clear by
+   * provider, the shape credential rotation needs.
+   */
+  prefixKeys = /* @__PURE__ */ new Map();
+  listeners = [];
+  planCounter = 0;
+  /** Resolves when the state backend finished restoring, awaited by flush to avoid races. */
+  restored;
+  constructor(options = {}) {
+    this.profiles = options.profiles;
+    this.pricing = options.pricing;
+    this.maxPrefixes = options.maxPrefixes ?? DEFAULT_MAX_PREFIXES;
+    this.clock = options.clock ?? (() => Date.now());
+    this.salt = String(options.seed ?? DEFAULT_SEED);
+    this.state = options.state;
+    this.ledger = new Ledger(this.pricing, this.maxPrefixes);
+    this.fingerprints = new Fingerprints(this.maxPrefixes);
+    this.keeper = new TtlKeeper(this.maxPrefixes);
+    this.restored = this.state === void 0 ? Promise.resolve() : this.restore(this.state);
+  }
+  plan(input) {
+    validatePlanInput(input);
+    const profile = resolveProfile(input.provider, this.profiles);
+    const now = this.clock();
+    const segmentHashes = /* @__PURE__ */ new Map();
+    for (const segment of input.segments) {
+      segmentHashes.set(segment.id, hashOf(segment));
+    }
+    const analysis = this.analyzer.analyze(input, profile);
+    const stableHashes = [];
+    for (const segment of input.segments.slice(0, analysis.orderedStableBoundary)) {
+      stableHashes.push(segmentHashes.get(segment.id) ?? "");
+    }
+    const prefixKey = combineKeys([
+      ...stableHashes,
+      input.provider,
+      input.model,
+      input.agentId ?? ""
+    ]);
+    let knownResource = false;
+    if (profile.family === "resource") {
+      const record = this.resources.get(prefixKey);
+      if (record !== void 0) {
+        if (now >= record.lastWriteAt + record.ttlSeconds * 1e3) {
+          this.resources.delete(prefixKey);
+        } else {
+          knownResource = true;
+        }
+      }
+    }
+    const result = this.planner.plan(
+      input,
+      profile,
+      analysis,
+      prefixKey,
+      this.pricing?.[input.model],
+      knownResource
+    );
+    const directives = result.directives.map((directive) => {
+      if (directive.kind !== "resource" || directive.action !== "reuse") {
+        return directive;
+      }
+      const record = this.resources.get(directive.resourceKey);
+      if (record !== void 0 && now >= record.lastWriteAt + RESOURCE_REFRESH_FRACTION * record.ttlSeconds * 1e3) {
+        return { ...directive, action: "refresh" };
+      }
+      return directive;
+    });
+    this.planCounter += 1;
+    const plan = {
+      planId: `rx-${this.planCounter}-${shortId(this.planCounter, this.salt)}`,
+      provider: input.provider,
+      model: input.model,
+      family: profile.family,
+      prefixKey,
+      stableTokens: analysis.stableTokens,
+      totalTokens: analysis.totalTokens,
+      directives,
+      findings: [...analysis.findings, ...result.extraFindings],
+      ...result.breakEven !== void 0 ? { breakEven: result.breakEven } : {},
+      reasoning: result.reasoning
+    };
+    const report = this.fingerprints.observe(
+      input,
+      prefixKey,
+      segmentHashes,
+      analysis.stableTokens,
+      now
+    );
+    if (report !== void 0) {
+      this.pushDrift(report);
+      this.emit({ type: "prefix.drifted", report });
+    }
+    if (!this.prefixKeys.has(prefixKey) && this.prefixKeys.size >= this.maxPrefixes) {
+      this.emit({
+        type: "limit.reached",
+        scope: "prefixes",
+        detail: `The ${this.maxPrefixes}-prefix cap is reached, plan for new prefix '${prefixKey}' was served without keep-warm tracking or resource bookkeeping.`,
+        timestamp: now
+      });
+    } else {
+      this.prefixKeys.set(prefixKey, input.provider);
+      this.keeper.track(plan, now);
+      this.applyResourceDirectives(input.provider, directives, now);
+    }
+    this.emit({ type: "plan.created", plan, timestamp: now });
+    return plan;
+  }
+  lint(input) {
+    validatePlanInput(input);
+    const profile = resolveProfile(input.provider, this.profiles);
+    return this.analyzer.analyze(input, profile).findings;
+  }
+  record(usage) {
+    validateUsage(usage);
+    const timestamp = usage.timestamp ?? this.clock();
+    const stamped = usage.timestamp !== void 0 ? usage : { ...usage, timestamp };
+    const { hit, evicted } = this.ledger.record(stamped);
+    this.emit({ type: "usage.recorded", usage: stamped, hit, timestamp });
+    if (evicted !== void 0) {
+      this.emit({
+        type: "limit.reached",
+        scope: "ledger",
+        detail: `The ledger evicted least-recently-used aggregate '${evicted}' to stay within its cap.`,
+        timestamp
+      });
+    }
+  }
+  stats(filter) {
+    return this.ledger.stats(filter);
+  }
+  schedule(now) {
+    const at = now ?? this.clock();
+    const due = this.keeper.due(at);
+    for (const entry of due) {
+      this.emit({ type: "refresh.due", entry, timestamp: at });
+    }
+    return due;
+  }
+  markRefreshed(prefixKey, now) {
+    this.keeper.markRefreshed(prefixKey, now ?? this.clock());
+  }
+  drifts(limit) {
+    if (limit === void 0) {
+      return [...this.driftRing];
+    }
+    if (limit <= 0) {
+      return [];
+    }
+    return this.driftRing.slice(-limit);
+  }
+  invalidate(filter) {
+    const now = this.clock();
+    const keyFilter = filter?.prefixKey;
+    const providerFilter = filter?.provider;
+    const matchesKey = (key) => keyFilter === void 0 || key === keyFilter;
+    const matched = /* @__PURE__ */ new Set();
+    for (const [key, provider] of this.prefixKeys) {
+      if (matchesKey(key) && (providerFilter === void 0 || provider === providerFilter)) {
+        matched.add(key);
+      }
+    }
+    for (const [key, record] of this.resources) {
+      if (matchesKey(key) && (providerFilter === void 0 || record.provider === providerFilter)) {
+        matched.add(key);
+      }
+    }
+    const pruned = this.fingerprints.prune(
+      (key) => providerFilter === void 0 ? matchesKey(key) : matched.has(key)
+    );
+    for (const key of pruned) {
+      matched.add(key);
+    }
+    for (const key of matched) {
+      this.prefixKeys.delete(key);
+      this.keeper.remove(key);
+      const record = this.resources.get(key);
+      if (record !== void 0) {
+        this.resources.delete(key);
+        this.emit({
+          type: "resource.action",
+          directive: {
+            kind: "resource",
+            action: "delete",
+            resourceKey: key,
+            ttlSeconds: record.ttlSeconds
+          },
+          timestamp: now
+        });
+      }
+    }
+    return matched.size;
+  }
+  profileOf(provider) {
+    return resolveProfile(provider, this.profiles);
+  }
+  on(listener) {
+    this.listeners.push(listener);
+    return () => {
+      const index = this.listeners.indexOf(listener);
+      if (index !== -1) {
+        this.listeners.splice(index, 1);
+      }
+    };
+  }
+  async flush() {
+    if (this.state === void 0) {
+      return;
+    }
+    await this.restored;
+    const resources = [];
+    for (const [key, record] of this.resources) {
+      resources.push({
+        key,
+        provider: record.provider,
+        ttlSeconds: record.ttlSeconds,
+        lastWriteAt: record.lastWriteAt
+      });
+    }
+    const snapshot = {
+      version: 1,
+      savedAt: this.clock(),
+      data: {
+        ledger: this.ledger.toJSON(),
+        fingerprints: this.fingerprints.toJSON(),
+        keeper: this.keeper.toJSON(),
+        resources,
+        drifts: [...this.driftRing]
+      }
+    };
+    await this.state.save(snapshot);
+  }
+  async close() {
+    await this.flush();
+    this.listeners.length = 0;
+  }
+  /** Appends one drift report, dropping the oldest beyond {@link DRIFT_RING_CAPACITY}. */
+  pushDrift(report) {
+    this.driftRing.push(report);
+    if (this.driftRing.length > DRIFT_RING_CAPACITY) {
+      this.driftRing.shift();
+    }
+  }
+  /**
+   * Mirrors resource directives into the registry and telemetry: create and refresh start
+   * a new TTL window, delete drops the record, reuse leaves the window untouched because
+   * reading a resource does not rewrite its server-side TTL.
+   */
+  applyResourceDirectives(provider, directives, now) {
+    for (const directive of directives) {
+      if (directive.kind !== "resource") {
+        continue;
+      }
+      if (directive.action === "delete") {
+        this.resources.delete(directive.resourceKey);
+      } else if (directive.action === "create" || directive.action === "refresh") {
+        this.resources.set(directive.resourceKey, {
+          provider,
+          ttlSeconds: directive.ttlSeconds,
+          lastWriteAt: now
+        });
+      }
+      this.emit({ type: "resource.action", directive, timestamp: now });
+    }
+  }
+  /** Synchronous fan-out over a copy of the listener list, exceptions swallowed. */
+  emit(event) {
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Defensive startup restore: each snapshot section is applied inside its own try/catch
+   * with structural checks first, so one corrupt section never poisons the others and a
+   * corrupt snapshot degrades to a fresh engine, never to a crash.
+   */
+  async restore(state) {
+    let snapshot;
+    try {
+      snapshot = await state.load();
+    } catch {
+      return;
+    }
+    if (snapshot === void 0) {
+      return;
+    }
+    const data = snapshot.data;
+    try {
+      const section = data.ledger;
+      if (isRecord(section) && typeof section.maxPrefixes === "number" && Array.isArray(section.entries)) {
+        this.ledger = Ledger.fromJSON(
+          { maxPrefixes: section.maxPrefixes, entries: section.entries },
+          this.pricing
+        );
+      }
+    } catch {
+    }
+    try {
+      const section = data.fingerprints;
+      if (isRecord(section) && typeof section.capacity === "number" && Array.isArray(section.entries)) {
+        this.fingerprints = Fingerprints.fromJSON({
+          capacity: section.capacity,
+          entries: section.entries
+        });
+      }
+    } catch {
+    }
+    try {
+      const section = data.keeper;
+      if (isRecord(section) && typeof section.capacity === "number" && Array.isArray(section.entries)) {
+        this.keeper = TtlKeeper.fromJSON({ capacity: section.capacity, entries: section.entries });
+      }
+    } catch {
+    }
+    try {
+      const section = data.resources;
+      if (Array.isArray(section)) {
+        for (const item of section) {
+          if (isResourceRecordJSON(item)) {
+            this.resources.set(item.key, {
+              provider: item.provider,
+              ttlSeconds: item.ttlSeconds,
+              lastWriteAt: item.lastWriteAt
+            });
+          }
+        }
+      }
+    } catch {
+    }
+    try {
+      const section = data.drifts;
+      if (Array.isArray(section)) {
+        const reports = [];
+        for (const item of section) {
+          if (isDriftReport(item)) {
+            reports.push(item);
+          }
+        }
+        this.driftRing.unshift(...reports.slice(-DRIFT_RING_CAPACITY));
+        while (this.driftRing.length > DRIFT_RING_CAPACITY) {
+          this.driftRing.shift();
+        }
+      }
+    } catch {
+    }
+    for (const entry of this.keeper.toJSON().entries) {
+      this.prefixKeys.set(entry.prefixKey, entry.provider);
+    }
+    for (const [key, record] of this.resources) {
+      this.prefixKeys.set(key, record.provider);
+    }
+  }
+};
+function createRACS(options = {}) {
+  return new RacsEngine(options);
+}
+
+// src/state/file.ts
+function hasErrnoCode(error, code) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function parseSnapshot(text, source) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new RacsError(
+      `RACS state at ${source} is not valid JSON: ${describe(error)}`,
+      "ERR_STATE_LOAD"
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new RacsError(
+      `RACS state at ${source} is not a snapshot object, found ${typeof parsed}.`,
+      "ERR_STATE_LOAD"
+    );
+  }
+  const record = parsed;
+  if (record.version !== 1) {
+    throw new RacsError(
+      `RACS state at ${source} has unsupported snapshot version ${String(record.version)}, expected 1.`,
+      "ERR_STATE_VERSION"
+    );
+  }
+  const savedAt = record.savedAt;
+  const data = record.data;
+  if (typeof savedAt !== "number" || typeof data !== "object" || data === null) {
+    throw new RacsError(
+      `RACS state at ${source} is missing the savedAt or data field of a version 1 snapshot.`,
+      "ERR_STATE_LOAD"
+    );
+  }
+  return { version: 1, savedAt, data };
+}
+function fileState(options) {
+  const { path } = options;
+  return {
+    async load() {
+      const fs = await import('node:fs/promises');
+      let text;
+      try {
+        text = await fs.readFile(path, "utf8");
+      } catch (error) {
+        if (hasErrnoCode(error, "ENOENT")) {
+          return void 0;
+        }
+        throw new RacsError(
+          `Failed to read RACS state from ${path}: ${describe(error)}`,
+          "ERR_STATE_LOAD"
+        );
+      }
+      return parseSnapshot(text, path);
+    },
+    async save(snapshot) {
+      const fs = await import('node:fs/promises');
+      const { dirname } = await import('node:path');
+      await fs.mkdir(dirname(path), { recursive: true });
+      const tmpPath = `${path}.tmp`;
+      await fs.writeFile(tmpPath, JSON.stringify(snapshot), "utf8");
+      await fs.rename(tmpPath, path);
+    }
+  };
+}
+
+// src/state/kv.ts
+function describe2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function parseSnapshot2(text, source) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new RacsError(
+      `RACS state at ${source} is not valid JSON: ${describe2(error)}`,
+      "ERR_STATE_LOAD"
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new RacsError(
+      `RACS state at ${source} is not a snapshot object, found ${typeof parsed}.`,
+      "ERR_STATE_LOAD"
+    );
+  }
+  const record = parsed;
+  if (record.version !== 1) {
+    throw new RacsError(
+      `RACS state at ${source} has unsupported snapshot version ${String(record.version)}, expected 1.`,
+      "ERR_STATE_VERSION"
+    );
+  }
+  const savedAt = record.savedAt;
+  const data = record.data;
+  if (typeof savedAt !== "number" || typeof data !== "object" || data === null) {
+    throw new RacsError(
+      `RACS state at ${source} is missing the savedAt or data field of a version 1 snapshot.`,
+      "ERR_STATE_LOAD"
+    );
+  }
+  return { version: 1, savedAt, data };
+}
+function kvState(kv, key = "racs:state") {
+  return {
+    async load() {
+      const raw = await kv.get(key);
+      if (raw === void 0 || raw === null) {
+        return void 0;
+      }
+      return parseSnapshot2(raw, `kv key "${key}"`);
+    },
+    async save(snapshot) {
+      await kv.set(key, JSON.stringify(snapshot));
+    }
+  };
+}
+
+// src/state/memory.ts
+function memoryState() {
+  let snapshot;
+  return {
+    load() {
+      return Promise.resolve(snapshot);
+    },
+    save(next) {
+      snapshot = next;
+      return Promise.resolve();
+    }
+  };
+}
+
+export { Ledger, PROVIDER_PROFILES, Planner, PrefixAnalyzer, RacsError, combineKeys, createRACS, estimateTokens, fileState, fnv1a64, kvState, memoryState, resolveProfile };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map