bantamkit-mcp 0.29.2 → 0.31.0

package/dist/memory/store.d.ts

@@ -15,8 +15,43 @@ export declare const VALID_TYPES: readonly ["feedback", "project", "reference",
  */
 export declare const DURABLE_TYPES: readonly ["feedback", "user"];
 export declare const DUPLICATE_JACCARD = 0.5;
+export declare const RECALL_MIN_SCORE_RATIO = 0;
 /** See the reference's comment: measured against a real store, not chosen. */
 export declare const DEFAULT_INDEX_BUDGET = 24000;
+/**
+ * Percent of the index budget that has to be SPENT before the store is called degraded.
+ *
+ * 90 and not 100 because the useful moment is before the refusal, not after it: at 100% the
+ * next `memory_save` has already failed and the operator has already seen the error. An
+ * INTEGER percent, compared by cross-multiplication where it is read, so the two runtimes
+ * cannot land on opposite sides of the line through a float they rounded differently.
+ *
+ * AMENDMENT (job46, J46-5, mirroring the reference's J46-4). It used to live in
+ * `mcp/status.ts`, next to the only thing that read it, and that is exactly what
+ * `docs/porting.md`'s register item 7 is about: the report warned at THIS line while the
+ * remedy it named — `compact` — aimed at a different one, so between the two the command
+ * exited 0 having archived nothing. `compact` has to know where the warning is to be able to
+ * clear it, and `mcp/status.ts` is above this layer, so the number moved DOWN to the layer
+ * both readers can reach. Same name, same value, same integer comparison; `mcp/status.ts`
+ * imports it and re-exports the name rather than spelling a second 90.
+ */
+export declare const INDEX_PRESSURE_PERCENT = 90;
+/**
+ * The largest index size `INDEX_PRESSURE_PERCENT` does NOT call degraded, in bytes.
+ *
+ * Integer arithmetic only, and the identity it holds is
+ * `size > undegradedIndexCeiling(b)` exactly when `size * 100 >= PERCENT * b` — the
+ * cross-multiplied comparison `mcp/status.ts`'s `indexPressureCondition` writes. The two
+ * spellings are pinned against each other by a boundary sweep in `test/server.test.mjs`,
+ * because they are two spellings and a test is the only thing that can keep them one line.
+ *
+ * `Math.floor` AND NOT `Math.trunc`, because the reference spells this `//` — floor division,
+ * which rounds toward -infinity — and `Math.trunc` rounds toward zero. The two differ on
+ * every negative budget, and a budget is not guaranteed positive by anything in this
+ * function's own signature. `test/store.test.mjs` sweeps both signs against a BigInt oracle
+ * rather than against a second copy of this expression.
+ */
+export declare function undegradedIndexCeiling(budget: number): number;
 export declare class MemoryValidationError extends BantamError {
 }
 export declare class MemoryBudgetExceeded extends BantamError {
@@ -55,6 +90,17 @@ export interface CompactResult {
     headroom: number;
     archiveDir: string;
 }
+/**
+ * The store members `dream.ts` needs and no caller outside it should have. See
+ * `MemoryStore.internals`.
+ */
+export interface StoreInternals {
+    facts(): Fact[];
+    factPath(name: FactValue): string;
+    indexLine(fact: Fact): string;
+    writeFact(fact: Fact): void;
+    rebuildIndex(): void;
+}
 export interface MemoryStoreOptions {
     indexBudget?: number;
     k?: number;
@@ -186,8 +232,25 @@ export declare class MemoryStore {
      * `[]` — the same answer as a real miss, which `component.Memory` used to turn into "no
      * memories matched. Try different words", telling a person to rephrase a question at a
      * filing cabinet nobody could open.
+     *
+     * `minRatio` is roadmap #6's precision gate: keep a fact only if its score is at least
+     * that fraction of the BEST score in this same recall. The default is
+     * `RECALL_MIN_SCORE_RATIO`, which is 0.0 and gates nothing — see the paragraph at that
+     * constant for why the number is a no-op today and what has to be measured before it
+     * stops being one. The comparison is relative to this store's own best because that is
+     * the only quantity in reach here that cancels query length; a layered `Memory` therefore
+     * applies the gate once per layer, against each layer's own top hit, and never across
+     * layers.
+     *
+     * THE RANGE CHECK RUNS BEFORE ANY FILE IS READ. A ratio outside `[0.0, 1.0]` is a
+     * caller's bug, and reporting it as "your store has no matches" would send someone to
+     * look at their memories for a defect that is in the argument. It is spelled
+     * `!(minRatio >= 0 && minRatio <= 1)` and NOT `(minRatio < 0 || minRatio > 1)`: every
+     * comparison against `NaN` is false, so the second spelling ADMITS `NaN` where the
+     * reference's `not 0.0 <= min_ratio <= 1.0` refuses it. That is a real mutant (M7b) and
+     * it is killed on both sides.
      */
-    recall(query: string, k?: number | null, stamp?: boolean): Fact[];
+    recall(query: string, k?: number | null, stamp?: boolean, minRatio?: number): Fact[];
     /**
      * `len(store._facts())` at the operator CLI, which is the only caller.
      *
@@ -216,6 +279,28 @@ export declare class MemoryStore {
      * store currently holds (capped at half the budget), so the headroom bought is "a fact as
      * big as your biggest one will fit", measured from this store's own data.
      *
+     * AMENDMENT (job46, J46-5, the port of the reference's J46-4), and it supersedes the
+     * sentence above about where that reserve is measured FROM. WAS: `budget - largest index
+     * line`. NOW: that same largest line plus the headroom `INDEX_PRESSURE_PERCENT` demands, so
+     * the target is `undegradedIndexCeiling(budget) - largest index line`. THE REASON IS
+     * `docs/porting.md`'s register item 7: the degraded report warns at 90% of the budget and
+     * names THIS command, while the old target sat at `budget - largest line`, so on any store
+     * whose biggest line is under a tenth of its budget the command the operator was told to
+     * run archived nothing and the warning stayed up. MEASURED on a read-only copy of this
+     * machine's project store (101 facts, index.md 21819 bytes of 24000 = 90.91%, largest index
+     * line 361 bytes, so the old target was 23639 = 98.50%): `compact()` answered
+     * `archived: []` and `index-budget-low` was still firing afterwards — the same two answers
+     * the reference gave on the same store, which is why the register calls this a defect of
+     * the reference and NOT a divergence. The paragraph above is why the fix is a substitution
+     * and not a new number — "a loop that stopped at 'fits' would archive nothing at the only
+     * moment the remedy is ever named" is the same argument one line lower down, so the reserve
+     * is measured from the line the WARNING draws instead of the one the REFUSAL draws.
+     *
+     * WHAT THIS DOES NOT CHANGE, deliberately: the eviction ORDER (`byEviction`), the
+     * half-the-budget cap, and an EXPLICIT `reserve`. A caller that passes one gets the
+     * arithmetic it always got, byte for byte — every eviction-order node in `store.test.mjs`
+     * passes one for exactly that reason, and so may any caller that needs the old default back.
+     *
      * `facts()` runs FIRST, before any rename, so an unreadable store moves nothing.
      *
      * THE MOVE IS `os.replace`, AND THE REFERENCE'S IS NOW TOO — the difference this comment
@@ -388,6 +473,21 @@ export declare class MemoryStore {
      * Registered as a runtime-py defect, not fixed here (invariant 8).
      */
     indexText(): string;
+    /**
+     * The `_`-prefixed members `dream.ts` reaches for, handed out as ONE named seam.
+     *
+     * The reference's `dream.py` calls `store._facts()`, `_fact_path`, `_index_line`,
+     * `_write_fact` and `_rebuild_index` directly — Python's underscore is a convention and
+     * costs nothing to cross. TypeScript's `private` is enforced, so the port needs a door,
+     * and this is deliberately one door rather than five relaxed modifiers: it is greppable,
+     * it names its one caller, and a sixth internal does not become reachable by accident.
+     *
+     * `_fact_text` has no member here because it never needed splitting out on this side —
+     * `formatFact` in `factfile.ts` has always been the serialiser `writeFact` calls, so the
+     * bytes `dream` MEASURES and the bytes the store WRITES are already one function. That is
+     * the code-shape difference the Python half had to manufacture, not a behaviour one.
+     */
+    internals(): StoreInternals;
     private factPath;
     private indexLine;
     /**

package/dist/memory/store.js

@@ -68,8 +68,93 @@ export const DURABLE_TYPES = ['feedback', 'user'];
 const NAME_RE = /^[a-z0-9][a-z0-9-]*\n?$/;
 const NAME_PATTERN = '^[a-z0-9][a-z0-9-]*$';
 export const DUPLICATE_JACCARD = 0.5;
+// ---- the precision gate (roadmap #6) ---------------------------------------------
+//
+// `recall` keeps a fact whose score is at least `minRatio` of the BEST score in the same
+// recall. WHY THIS NUMBER IS 0.0, and what will replace it:
+//
+// 0.0 IS A DELIBERATE NO-OP, not a tuned value. `score >= 0.0 * best` is true for every
+// fact `recall` was ever going to return — the scoring loop keeps only `score > 0` — so
+// shipping this gate at its default changes not one recall, not one injected header, and
+// not one byte of any reply. That is the whole point. The threshold that would actually
+// cut something has to come from `tools/ledger/injection-precision.mjs`, and on the day
+// that tool shipped (2026-09-06) it REFUSED to report a rate: 491 injection records, 3 of
+// them carrying names+scores+session, 2 distinct sessions, and no control arm, against a
+// floor of 100 joinable injections across 5 sessions. There is no retroactive baseline —
+// the 488 older records carry `hits` and `bytes` and nothing joinable — so a number chosen
+// today would be a number chosen off three rows, shipped as a silent suppressor of memory
+// injection. The mechanism lands now; the number lands when that tool answers instead of
+// refusing.
+//
+// WHY A RATIO AND NOT A COUNT. `score` is an unnormalised intersection size,
+// `len(tokens(name + " " + description) & tokens(query))`, so it scales with how long the
+// QUERY is. Measured on the three instrumented records: the same two-fact shape scored 2
+// and 2 on a 452-character prompt, 4 and 4 on a 453-character prompt, and 22 and 21 on a
+// 7855-character one. An absolute cut of, say, 5 would gate out both short prompts
+// entirely and admit everything on the long one, which is a rule about prompt length
+// wearing a relevance costume. Within ONE recall the query is fixed, so dividing by the
+// best score in that same recall cancels the length term exactly. Jaccard was the other
+// candidate and was rejected for the mirror-image bias: `|a & b| / |a | b|` puts the
+// query's own token count in the denominator, so it would gate out LONG prompts instead.
+//
+// THE GATE IS RELATIVE, SO IT CAN NEVER EMPTY A RECALL. The top hit IS the max, so
+// `best >= minRatio * best` holds for every ratio in range, 1.0 included. It narrows an
+// injection; it never suppresses one, and the COUNT of prompts that get an injection is
+// invariant at every setting.
+//
+// WHAT THE RATIO DOES NOT FIX: `tokens` is `re.findall(r"[a-z0-9]+", text.lower())`,
+// ASCII-only. A wholly non-Latin prompt tokenises to the empty set and scores 0 against
+// every fact, so it never reaches this gate at all — it is already an empty recall. This
+// store's operator writes Thai; a threshold tuned on English prompts would be tuned on a
+// population that structurally excludes theirs.
+//
+// The number lives in TWO places, one per runtime, and they must hold the SAME float:
+// `runtime-py/src/bantamkit/memory/store.py`'s `RECALL_MIN_SCORE_RATIO` is the reference.
+// `Memory.recallOutcome` and the `UserPromptSubmit` hook that calls it inherit it rather
+// than restating it.
+export const RECALL_MIN_SCORE_RATIO = 0.0;
+// Spelled once because both runtimes raise it verbatim. The offending value is NOT
+// interpolated: Python renders `2.0` as `2.0` and JavaScript renders it as `2`, so a
+// sentence carrying the number would be a divergence manufactured by float formatting.
+const MIN_RATIO_RANGE = 'recall min-score ratio must be between 0.0 and 1.0';
 /** See the reference's comment: measured against a real store, not chosen. */
 export const DEFAULT_INDEX_BUDGET = 24_000;
+/**
+ * Percent of the index budget that has to be SPENT before the store is called degraded.
+ *
+ * 90 and not 100 because the useful moment is before the refusal, not after it: at 100% the
+ * next `memory_save` has already failed and the operator has already seen the error. An
+ * INTEGER percent, compared by cross-multiplication where it is read, so the two runtimes
+ * cannot land on opposite sides of the line through a float they rounded differently.
+ *
+ * AMENDMENT (job46, J46-5, mirroring the reference's J46-4). It used to live in
+ * `mcp/status.ts`, next to the only thing that read it, and that is exactly what
+ * `docs/porting.md`'s register item 7 is about: the report warned at THIS line while the
+ * remedy it named — `compact` — aimed at a different one, so between the two the command
+ * exited 0 having archived nothing. `compact` has to know where the warning is to be able to
+ * clear it, and `mcp/status.ts` is above this layer, so the number moved DOWN to the layer
+ * both readers can reach. Same name, same value, same integer comparison; `mcp/status.ts`
+ * imports it and re-exports the name rather than spelling a second 90.
+ */
+export const INDEX_PRESSURE_PERCENT = 90;
+/**
+ * The largest index size `INDEX_PRESSURE_PERCENT` does NOT call degraded, in bytes.
+ *
+ * Integer arithmetic only, and the identity it holds is
+ * `size > undegradedIndexCeiling(b)` exactly when `size * 100 >= PERCENT * b` — the
+ * cross-multiplied comparison `mcp/status.ts`'s `indexPressureCondition` writes. The two
+ * spellings are pinned against each other by a boundary sweep in `test/server.test.mjs`,
+ * because they are two spellings and a test is the only thing that can keep them one line.
+ *
+ * `Math.floor` AND NOT `Math.trunc`, because the reference spells this `//` — floor division,
+ * which rounds toward -infinity — and `Math.trunc` rounds toward zero. The two differ on
+ * every negative budget, and a budget is not guaranteed positive by anything in this
+ * function's own signature. `test/store.test.mjs` sweeps both signs against a BigInt oracle
+ * rather than against a second copy of this expression.
+ */
+export function undegradedIndexCeiling(budget) {
+    return Math.floor((INDEX_PRESSURE_PERCENT * budget - 1) / 100);
+}
 // The second half of the "unreadable" sentence, one per directory this store lists — and
 // then the same distinction one syscall down, for the stats `restore` does instead of a
 // listing. They are separate strings because the failures do different damage, and an error
@@ -494,11 +579,30 @@ export class MemoryStore {
      * `[]` — the same answer as a real miss, which `component.Memory` used to turn into "no
      * memories matched. Try different words", telling a person to rephrase a question at a
      * filing cabinet nobody could open.
+     *
+     * `minRatio` is roadmap #6's precision gate: keep a fact only if its score is at least
+     * that fraction of the BEST score in this same recall. The default is
+     * `RECALL_MIN_SCORE_RATIO`, which is 0.0 and gates nothing — see the paragraph at that
+     * constant for why the number is a no-op today and what has to be measured before it
+     * stops being one. The comparison is relative to this store's own best because that is
+     * the only quantity in reach here that cancels query length; a layered `Memory` therefore
+     * applies the gate once per layer, against each layer's own top hit, and never across
+     * layers.
+     *
+     * THE RANGE CHECK RUNS BEFORE ANY FILE IS READ. A ratio outside `[0.0, 1.0]` is a
+     * caller's bug, and reporting it as "your store has no matches" would send someone to
+     * look at their memories for a defect that is in the argument. It is spelled
+     * `!(minRatio >= 0 && minRatio <= 1)` and NOT `(minRatio < 0 || minRatio > 1)`: every
+     * comparison against `NaN` is false, so the second spelling ADMITS `NaN` where the
+     * reference's `not 0.0 <= min_ratio <= 1.0` refuses it. That is a real mutant (M7b) and
+     * it is killed on both sides.
      */
-    recall(query, k = null, stamp = true) {
+    recall(query, k = null, stamp = true, minRatio = RECALL_MIN_SCORE_RATIO) {
+        if (!(minRatio >= 0 && minRatio <= 1))
+            throw new MemoryValidationError(MIN_RATIO_RANGE);
         const limit = k ?? this.k;
         const q = tokens(query);
-        const scored = [];
+        let scored = [];
         for (const fact of this.facts()) {
             let score = 0;
             for (const t of tokens(`${pyText(fact.name)} ${pyText(fact.description)}`))
@@ -507,6 +611,20 @@ export class MemoryStore {
             if (score > 0)
                 scored.push({ score, name: fact.name, fact });
         }
+        if (scored.length > 0) {
+            // No `if (minRatio > 0)` shortcut on purpose: at 0.0 this line still runs and still
+            // keeps everything, so "the default gates nothing" is a fact about the arithmetic
+            // rather than about a branch that could be edited away. `Math.max(...scored)` is NOT
+            // used: a spread is one argument per fact and a large store would overflow the
+            // argument limit, which is a crash the reference's `max(...)` over a generator does
+            // not have.
+            let best = scored[0].score;
+            for (const s of scored)
+                if (s.score > best)
+                    best = s.score;
+            const floor = minRatio * best;
+            scored = scored.filter((s) => s.score >= floor);
+        }
         // `key=lambda pair: (-pair[0], pair[1].name)`. The name comparison is CODEPOINT order
         // for two strings — which is not what `Array.prototype.sort` does — and Python's `<`
         // for everything else, refusals included. See `sortScored`.
@@ -553,6 +671,28 @@ export class MemoryStore {
      * store currently holds (capped at half the budget), so the headroom bought is "a fact as
      * big as your biggest one will fit", measured from this store's own data.
      *
+     * AMENDMENT (job46, J46-5, the port of the reference's J46-4), and it supersedes the
+     * sentence above about where that reserve is measured FROM. WAS: `budget - largest index
+     * line`. NOW: that same largest line plus the headroom `INDEX_PRESSURE_PERCENT` demands, so
+     * the target is `undegradedIndexCeiling(budget) - largest index line`. THE REASON IS
+     * `docs/porting.md`'s register item 7: the degraded report warns at 90% of the budget and
+     * names THIS command, while the old target sat at `budget - largest line`, so on any store
+     * whose biggest line is under a tenth of its budget the command the operator was told to
+     * run archived nothing and the warning stayed up. MEASURED on a read-only copy of this
+     * machine's project store (101 facts, index.md 21819 bytes of 24000 = 90.91%, largest index
+     * line 361 bytes, so the old target was 23639 = 98.50%): `compact()` answered
+     * `archived: []` and `index-budget-low` was still firing afterwards — the same two answers
+     * the reference gave on the same store, which is why the register calls this a defect of
+     * the reference and NOT a divergence. The paragraph above is why the fix is a substitution
+     * and not a new number — "a loop that stopped at 'fits' would archive nothing at the only
+     * moment the remedy is ever named" is the same argument one line lower down, so the reserve
+     * is measured from the line the WARNING draws instead of the one the REFUSAL draws.
+     *
+     * WHAT THIS DOES NOT CHANGE, deliberately: the eviction ORDER (`byEviction`), the
+     * half-the-budget cap, and an EXPLICIT `reserve`. A caller that passes one gets the
+     * arithmetic it always got, byte for byte — every eviction-order node in `store.test.mjs`
+     * passes one for exactly that reason, and so may any caller that needs the old default back.
+     *
      * `facts()` runs FIRST, before any rename, so an unreadable store moves nothing.
      *
      * THE MOVE IS `os.replace`, AND THE REFERENCE'S IS NOW TOO — the difference this comment
@@ -607,8 +747,19 @@ export class MemoryStore {
             sizes.set(pyHashKey(fact.name), Buffer.byteLength(this.indexLine(fact), 'utf8'));
         }
         const all = [...sizes.values()];
-        if (reserve === null)
-            reserve = all.length === 0 ? 0 : Math.max(...all);
+        if (reserve === null) {
+            // The default reserve is measured from the WARNING LINE, not from the budget. One
+            // substitution, and it is the whole of `docs/porting.md` item 7: the sentence that
+            // names this command fires at `INDEX_PRESSURE_PERCENT`, so a remedy that only reaches
+            // `budget - largest line` is a no-op everywhere between them. `undegradedIndexCeiling`
+            // is that line; `+ largest line` keeps this method's own promise on the other side of
+            // it, unchanged in words: "a fact as big as your biggest one will fit" — before the
+            // index is degraded AGAIN, rather than before it is over budget.
+            reserve =
+                this.indexBudget -
+                    undegradedIndexCeiling(this.indexBudget) +
+                    (all.length === 0 ? 0 : Math.max(...all));
+        }
         // `min(reserve, self.index_budget // 2)`: floor division, and the budget is >= 1 here
         // because both CLIs refuse a smaller one at the edge.
         reserve = Math.max(0, Math.min(reserve, Math.floor(this.indexBudget / 2)));
@@ -839,6 +990,29 @@ export class MemoryStore {
     indexText() {
         return this.facts().map((fact) => this.indexLine(fact)).join('');
     }
+    /**
+     * The `_`-prefixed members `dream.ts` reaches for, handed out as ONE named seam.
+     *
+     * The reference's `dream.py` calls `store._facts()`, `_fact_path`, `_index_line`,
+     * `_write_fact` and `_rebuild_index` directly — Python's underscore is a convention and
+     * costs nothing to cross. TypeScript's `private` is enforced, so the port needs a door,
+     * and this is deliberately one door rather than five relaxed modifiers: it is greppable,
+     * it names its one caller, and a sixth internal does not become reachable by accident.
+     *
+     * `_fact_text` has no member here because it never needed splitting out on this side —
+     * `formatFact` in `factfile.ts` has always been the serialiser `writeFact` calls, so the
+     * bytes `dream` MEASURES and the bytes the store WRITES are already one function. That is
+     * the code-shape difference the Python half had to manufacture, not a behaviour one.
+     */
+    internals() {
+        return {
+            facts: () => this.facts(),
+            factPath: (name) => this.factPath(name),
+            indexLine: (fact) => this.indexLine(fact),
+            writeFact: (fact) => this.writeFact(fact),
+            rebuildIndex: () => this.rebuildIndex(),
+        };
+    }
     // ---- internals ----
     factPath(name) {
         return pyJoin(this.root, 'facts', `${pyText(name)}.md`);

package/dist/pricing.d.ts

@@ -0,0 +1,100 @@
+import { BantamError } from './errors.js';
+export declare const PRICES_ENV = "BANTAMKIT_PRICES";
+export declare const PRICE_SCHEMA_VERSION = 1;
+export declare const CURRENCY = "USD";
+export declare const RATE_UNIT = "micro_usd_per_million_tokens";
+/** A rate is micro-USD per this many tokens. */
+export declare const TOKENS_PER_RATE_UNIT = 1000000;
+/** Micro-USD in one USD. Also the rounding divisor, hence `HALF` below. */
+export declare const MICROS_PER_UNIT = 1000000;
+/** The largest integer both runtimes represent exactly. */
+export declare const MAX_SAFE_INT: number;
+/**
+ * The four classes the host's own `usage` block distinguishes, in the order the ledger
+ * accumulates them. This tuple is the unit of pricing; see property 1 in the reference.
+ */
+export declare const TOKEN_CLASSES: readonly ["input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "output_tokens"];
+export type TokenClass = (typeof TOKEN_CLASSES)[number];
+export interface Rate {
+    recorded: string;
+    source: string;
+    [cls: string]: string | number;
+}
+export interface PriceTable {
+    schema_version: number;
+    currency: string;
+    unit: string;
+    note?: string;
+    rates: Record<string, Rate>;
+}
+/** A cost, or a refusal. Never both, and never a zero standing in for a refusal. */
+export type PriceResult = {
+    unavailable: string;
+} | {
+    model: string;
+    currency: string;
+    micros: number;
+    amount: string;
+    breakdown: Record<string, number>;
+    rate: Rate;
+};
+/**
+ * The table on disk is malformed.
+ *
+ * This THROWS rather than returning `{unavailable}`, and the split is deliberate: a broken
+ * price table is an operator configuration fault that must stop and name itself, while an
+ * unpriced model is a normal, expected answer that a caller keeps working past.
+ */
+export declare class PriceTableError extends BantamError {
+}
+/**
+ * `$BANTAMKIT_PRICES` verbatim if set, else the shipped table in the asset pack.
+ *
+ * The override wins even when it is wrong -- same arm order and same reasoning as
+ * `assetsRoot()`: an override that points nowhere must fail naming itself rather than fall
+ * through to a table the operator did not ask for.
+ */
+export declare function priceTablePath(): string;
+/**
+ * Read and validate a price table. `path` is used VERBATIM in every message it appears in,
+ * never normalised, because `Path('./x')` is `x` on the reference side and `./x` here and the
+ * fault sentence would then differ over a path neither runtime chose.
+ */
+export declare function loadPriceTable(path?: string): PriceTable;
+/**
+ * The decode both runtimes must agree on, in one place so the gate can reach it.
+ *
+ * This side is already the strict one -- `JSON.parse` rejects the bare `NaN` / `Infinity` /
+ * `-Infinity` tokens that `json.loads` accepts -- so the function is a plain `JSON.parse`
+ * and the reference is what had to move. It exists as a named arm anyway, because a rule
+ * that lives in only one of two runtimes is a rule the conformance harness cannot reach.
+ */
+export declare function decodePriceJson(text: string): unknown;
+/**
+ * Every rule the table must satisfy, each with its own sentence.
+ *
+ * Returns a NORMALISED table: the top-level keys in a fixed order, rate names in code-point
+ * order, and every count narrowed. See the reference for the ONE thing normalisation cannot
+ * buy -- the iteration order of `rates` for a model name JavaScript reads as an array index.
+ */
+export declare function validatePriceTable(raw: unknown): PriceTable;
+/**
+ * Micro-USD as a fixed-6-decimal string, built from integers only.
+ *
+ * Non-negative input only; every producer in this module is a sum of non-negative products.
+ */
+export declare function formatMicros(micros: number): string;
+/**
+ * The cost of one `usage` block under one model's rate, or a named refusal.
+ *
+ * `table` must be a table `validatePriceTable` returned.
+ *
+ * THE ORDER OF THE CHECKS IS PART OF THE CONTRACT. The usage is validated BEFORE the model is
+ * looked up, so a caller who passed a malformed usage is told that, rather than being sent to
+ * edit a price table over a bug in the call.
+ *
+ * THE USAGE MUST CARRY ALL FOUR CLASSES AND NOTHING ELSE. See the reference: a token class
+ * silently ignored is money silently dropped, and a class silently defaulted to zero is money
+ * silently invented.
+ */
+export declare function priceTokens(table: PriceTable, model: string, usage: unknown): PriceResult;