bantamkit-mcp 0.30.0 → 0.31.0

package/dist/mcp/status.d.ts

@@ -1,5 +1,7 @@
 import type { EventLog } from '../eventlog.js';
 import { Memory } from '../memory/component.js';
+import { INDEX_PRESSURE_PERCENT } from '../memory/store.js';
+import type { Install } from './identity.js';
 /**
  * The tool AND the prompt answer to this one name. Deliberately the same word: the operator
  * who read `bantamkit_status` in a footer must find it in their prompt menu without
@@ -31,14 +33,13 @@ export declare const STATUS_PROMPT_TAIL: string;
 export declare const SERVED_PROMPTS = 1;
 export declare const SERVED_RESOURCE_TEMPLATES = 2;
 /**
- * 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 below, so the two runtimes cannot land
- * on opposite sides of the line through a float they rounded differently.
+ * `INDEX_PRESSURE_PERCENT` is re-exported here, where it used to be DEFINED, so that
+ * `import { INDEX_PRESSURE_PERCENT } from './mcp/status.js'` keeps resolving. It moved down
+ * to `memory/store.ts` in job46 (J46-5, mirroring the reference's J46-4):
+ * `MemoryStore.compact` is the remedy the sentence below names, and it cannot clear a warning
+ * whose line it cannot see. The comment that says why the number is 90 moved with it.
  */
-export declare const INDEX_PRESSURE_PERCENT = 90;
+export { INDEX_PRESSURE_PERCENT };
 /**
  * One thing that is wrong, carried in the two forms the two surfaces need.
  *
@@ -135,6 +136,20 @@ export declare function unreadableLayerCondition(memory: Memory): Condition | nu
  * not a divergence and is not fixed here; it is registered in `docs/porting.md`. The sentence
  * says "archive or shorten facts", which is what the operator has to do either way.
  *
+ * AMENDMENT (job46, J46-5): THE PARAGRAPH ABOVE IS A RECORD OF A DEFECT THAT IS NOW CLOSED,
+ * and it is left standing because it is the measurement that motivated the fix. What it says
+ * was true until this job: the band was real, and on this machine's own project store
+ * (101 facts, index.md 21819 bytes of a 24000-byte budget = 90.91%, largest index line 361
+ * bytes so the old target was 23639 = 98.50%) `compact()` answered `archived: []` with this
+ * very sentence on screen. What has changed is the second half — "is not fixed here". It is
+ * fixed now, in the layer that owns it: `MemoryStore.compact`'s default `reserve` is measured
+ * from `undegradedIndexCeiling(budget)` rather than from `budget`, so running the command
+ * this sentence names clears the condition this sentence reports. Both runtimes moved in the
+ * same job (the reference in `87cc1f7`), because a band that closed on one side only would be
+ * the divergence the paragraph above correctly said this was not. The register entry's own
+ * closure is not written here — that is a `docs/porting.md` edit, and it waits on a
+ * conformance case comparing the two answers.
+ *
  * THIS SENTENCE IS FOR THE OPERATOR; THE MODEL HAS ITS OWN REMEDY. Since job42 the model
  * can call `memory_compact` (the ninth served tool) when a save is actually refused, and
  * the refused-budget reply in `memory/component.ts` names it. That does not change this
@@ -152,13 +167,40 @@ export declare function indexPressureCondition(memory: Memory): Condition | null
  * BOTH on and known to have lost a record is a problem anyone can act on.
  */
 export declare function eventLogCondition(log: EventLog): Condition | null;
+/**
+ * This install came from a path on this machine, and that path is gone.
+ *
+ * THE ONE CONDITION THAT NAMES A PATH, and the exception is deliberate. Every other sentence
+ * here refuses one because `assetsRoot()` resolves differently in the two runtimes by
+ * construction, so a path would be an uncomparable value bought for nothing. This path is not
+ * the server's own location — it is the origin THE INSTALLER WROTE DOWN, it is the entire
+ * actionable content of the finding (AS-7's measured case is a tarball under a
+ * `/private/tmp/.../scratchpad` that no longer exists), and a sentence saying "something is
+ * missing" without saying what would be a sentence nobody can act on.
+ *
+ * THE REMEDY IS THE ONE THAT ACTUALLY MOVES SOMETHING. J46-4 spent a unit removing a condition
+ * whose remedy exited 0 having changed nothing, and this is exactly the shape that invites
+ * another: `npm update` where a dangling `file:` install lives is a no-op BY CONSTRUCTION. So
+ * the sentence sends the reader at a reinstall BY NAME from a registry, which replaces the
+ * install rather than trying to refresh it in place. `bantamkit` is the PRODUCT name and is
+ * copied verbatim from the reference — it is not the npm package id, and turning it into one
+ * is how `git_commit` diverged on a noun.
+ *
+ * THE DERIVED HALF IS MEMOISED AND THIS HALF IS NOT: the shape cannot change under a running
+ * process, the path's existence can, and it is the one that has to be read now.
+ */
+export declare function installSourceCondition(install: Install | null): Condition | null;
 /**
  * Everything wrong right now, worst first. An empty array means healthy.
  *
  * ORDER IS SEVERITY AND IT IS LOAD-BEARING, because the footer shows the first one: a pack
  * that vanished breaks every asset-backed surface; an unreadable layer makes recall ANSWER
  * WRONGLY rather than fail; a full index refuses the next save; a broken event log costs
- * diagnostics only.
+ * diagnostics only; and a dangling install origin costs nothing AT ALL right now — the server
+ * is serving correctly, and what is broken is the next attempt to update it. That is why it is
+ * last despite being the one that went unnoticed for five releases
+ * (`docs/roadmap-agent-stack.md` AS-7): severity here is what is failing, not what has been
+ * failing longest.
  *
  * EVERY CONDITION IS OBSERVED, NOT INFERRED — no heartbeat, no timer, no last-seen timestamp.
  * Each one is a state a test can construct and then watch this report: delete the pack, make a
@@ -167,8 +209,10 @@ export declare function eventLogCondition(log: EventLog): Condition | null;
  * claimed.
  *
  * THE COST, because this runs on every tool call: one `stat` for the index, one `stat` for the
- * pack, one directory listing per memory layer (two to four), and a field read for the log. No
- * fact file is opened and no index is parsed.
+ * pack, one directory listing per memory layer (two to four), a field read for the log, and one
+ * `stat` for the install origin. No fact file is opened, no index is parsed, and
+ * `node_modules` is NOT walked for a hidden lockfile — `currentInstall` does that once per
+ * process, because the bytes that were imported cannot change under a running one.
  */
 export declare function degradedConditions(memory: Memory, log: EventLog): Condition[];
 /**

package/dist/mcp/status.js

@@ -33,6 +33,8 @@ import { statSync } from 'node:fs';
 import { join } from 'node:path';
 import { AssetNotFound, assetsRoot } from '../assets.js';
 import { Memory } from '../memory/component.js';
+import { INDEX_PRESSURE_PERCENT } from '../memory/store.js';
+import { Undetermined, currentInstall, originStat } from './identity.js';
 /**
  * The tool AND the prompt answer to this one name. Deliberately the same word: the operator
  * who read `bantamkit_status` in a footer must find it in their prompt menu without
@@ -68,14 +70,13 @@ export const STATUS_PROMPT_TAIL = 'Show me that report as it stands. If it says
 export const SERVED_PROMPTS = 1;
 export const SERVED_RESOURCE_TEMPLATES = 2;
 /**
- * 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 below, so the two runtimes cannot land
- * on opposite sides of the line through a float they rounded differently.
+ * `INDEX_PRESSURE_PERCENT` is re-exported here, where it used to be DEFINED, so that
+ * `import { INDEX_PRESSURE_PERCENT } from './mcp/status.js'` keeps resolving. It moved down
+ * to `memory/store.ts` in job46 (J46-5, mirroring the reference's J46-4):
+ * `MemoryStore.compact` is the remedy the sentence below names, and it cannot clear a warning
+ * whose line it cannot see. The comment that says why the number is 90 moved with it.
  */
-export const INDEX_PRESSURE_PERCENT = 90;
+export { INDEX_PRESSURE_PERCENT };
 /** `1 prompt` / `2 prompts`. Spelled once so the two runtimes cannot disagree twice. */
 export function plural(count, word) {
     return count === 1 ? `${count} ${word}` : `${count} ${word}s`;
@@ -221,6 +222,20 @@ export function unreadableLayerCondition(memory) {
  * not a divergence and is not fixed here; it is registered in `docs/porting.md`. The sentence
  * says "archive or shorten facts", which is what the operator has to do either way.
  *
+ * AMENDMENT (job46, J46-5): THE PARAGRAPH ABOVE IS A RECORD OF A DEFECT THAT IS NOW CLOSED,
+ * and it is left standing because it is the measurement that motivated the fix. What it says
+ * was true until this job: the band was real, and on this machine's own project store
+ * (101 facts, index.md 21819 bytes of a 24000-byte budget = 90.91%, largest index line 361
+ * bytes so the old target was 23639 = 98.50%) `compact()` answered `archived: []` with this
+ * very sentence on screen. What has changed is the second half — "is not fixed here". It is
+ * fixed now, in the layer that owns it: `MemoryStore.compact`'s default `reserve` is measured
+ * from `undegradedIndexCeiling(budget)` rather than from `budget`, so running the command
+ * this sentence names clears the condition this sentence reports. Both runtimes moved in the
+ * same job (the reference in `87cc1f7`), because a band that closed on one side only would be
+ * the divergence the paragraph above correctly said this was not. The register entry's own
+ * closure is not written here — that is a `docs/porting.md` edit, and it waits on a
+ * conformance case comparing the two answers.
+ *
  * THIS SENTENCE IS FOR THE OPERATOR; THE MODEL HAS ITS OWN REMEDY. Since job42 the model
  * can call `memory_compact` (the ninth served tool) when a save is actually refused, and
  * the refused-budget reply in `memory/component.ts` names it. That does not change this
@@ -261,13 +276,71 @@ export function eventLogCondition(log) {
             'whether its directory is writable.',
     };
 }
+/**
+ * This install came from a path on this machine, and that path is gone.
+ *
+ * THE ONE CONDITION THAT NAMES A PATH, and the exception is deliberate. Every other sentence
+ * here refuses one because `assetsRoot()` resolves differently in the two runtimes by
+ * construction, so a path would be an uncomparable value bought for nothing. This path is not
+ * the server's own location — it is the origin THE INSTALLER WROTE DOWN, it is the entire
+ * actionable content of the finding (AS-7's measured case is a tarball under a
+ * `/private/tmp/.../scratchpad` that no longer exists), and a sentence saying "something is
+ * missing" without saying what would be a sentence nobody can act on.
+ *
+ * THE REMEDY IS THE ONE THAT ACTUALLY MOVES SOMETHING. J46-4 spent a unit removing a condition
+ * whose remedy exited 0 having changed nothing, and this is exactly the shape that invites
+ * another: `npm update` where a dangling `file:` install lives is a no-op BY CONSTRUCTION. So
+ * the sentence sends the reader at a reinstall BY NAME from a registry, which replaces the
+ * install rather than trying to refresh it in place. `bantamkit` is the PRODUCT name and is
+ * copied verbatim from the reference — it is not the npm package id, and turning it into one
+ * is how `git_commit` diverged on a noun.
+ *
+ * THE DERIVED HALF IS MEMOISED AND THIS HALF IS NOT: the shape cannot change under a running
+ * process, the path's existence can, and it is the one that has to be read now.
+ */
+export function installSourceCondition(install) {
+    if (install === null || install.source === null)
+        return null;
+    // `present: null` is a check that could not be made, and the reference reports no condition
+    // for one either: an origin nobody may stat is not, on that evidence, an origin that is gone.
+    if (originStat(install.source).present !== false)
+        return null;
+    return {
+        key: 'install-source-missing',
+        sentence: `this server was installed from ${install.source}, which no longer exists, so nothing ` +
+            'can be refreshed in place there — reinstall bantamkit by name from a package registry ' +
+            'and restart the server.',
+    };
+}
+/**
+ * The shape, or nothing. A shape that could not be derived is a REPORTED gap.
+ *
+ * `buildIdentity` is where that gap is named, with its reason. It is not a degraded condition:
+ * an install this code cannot classify is not, on that evidence, an install that is broken, and
+ * a footer on every tool call saying otherwise would be the noise `degradedNotice` exists to
+ * avoid.
+ */
+function currentInstallOrNull() {
+    try {
+        return currentInstall();
+    }
+    catch (e) {
+        if (!(e instanceof Undetermined))
+            throw e;
+        return null;
+    }
+}
 /**
  * Everything wrong right now, worst first. An empty array means healthy.
  *
  * ORDER IS SEVERITY AND IT IS LOAD-BEARING, because the footer shows the first one: a pack
  * that vanished breaks every asset-backed surface; an unreadable layer makes recall ANSWER
  * WRONGLY rather than fail; a full index refuses the next save; a broken event log costs
- * diagnostics only.
+ * diagnostics only; and a dangling install origin costs nothing AT ALL right now — the server
+ * is serving correctly, and what is broken is the next attempt to update it. That is why it is
+ * last despite being the one that went unnoticed for five releases
+ * (`docs/roadmap-agent-stack.md` AS-7): severity here is what is failing, not what has been
+ * failing longest.
  *
  * EVERY CONDITION IS OBSERVED, NOT INFERRED — no heartbeat, no timer, no last-seen timestamp.
  * Each one is a state a test can construct and then watch this report: delete the pack, make a
@@ -276,8 +349,10 @@ export function eventLogCondition(log) {
  * claimed.
  *
  * THE COST, because this runs on every tool call: one `stat` for the index, one `stat` for the
- * pack, one directory listing per memory layer (two to four), and a field read for the log. No
- * fact file is opened and no index is parsed.
+ * pack, one directory listing per memory layer (two to four), a field read for the log, and one
+ * `stat` for the install origin. No fact file is opened, no index is parsed, and
+ * `node_modules` is NOT walked for a hidden lockfile — `currentInstall` does that once per
+ * process, because the bytes that were imported cannot change under a running one.
  */
 export function degradedConditions(memory, log) {
     return [
@@ -285,6 +360,7 @@ export function degradedConditions(memory, log) {
         unreadableLayerCondition(memory),
         indexPressureCondition(memory),
         eventLogCondition(log),
+        installSourceCondition(currentInstallOrNull()),
     ].filter((condition) => condition !== null);
 }
 /**

package/dist/memory/cli.js

@@ -4,7 +4,7 @@
  *
  * `docs/memory.md` states, as a design decision, that `lint`, `archived` and `restore`
  * are **not** agent tools — "lifecycle is an operator decision, not a model decision" —
- * and the thirteen-tool surface holds to it; `compact` is the one exception since job42
+ * and the fourteen-tool surface holds to it; `compact` is the one exception since job42
  * (`memory_compact`, the on-refusal path the model reaches itself). `runtime-py` made that
  * position coherent in August 2026 by giving the operator `python -m bantamkit.memory`.
  * `runtime-ts` did not. MEASURED 2026-08-24 before this file existed: `node dist/cli.js -h`

package/dist/memory/store.d.ts

@@ -18,6 +18,40 @@ 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 {
@@ -245,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

package/dist/memory/store.js

@@ -119,6 +119,42 @@ export const RECALL_MIN_SCORE_RATIO = 0.0;
 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
@@ -635,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
@@ -689,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)));

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;