bantamkit-mcp 0.35.1 → 0.35.2

package/dist/mcp/status.js

@@ -34,6 +34,7 @@ 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 { updateLine } from '../updatecheck.js';
 import { Undetermined, currentInstall, originStat } from './identity.js';
 /**
  * The tool AND the prompt answer to this one name. Deliberately the same word: the operator
@@ -423,6 +424,19 @@ export function statusReport(memory, log, conditions, identity, tools, prompts,
             (size === null ? 'unreadable' : String(size)) +
             ` of ${budget} bytes`,
         `event log: ${log.enabled ? 'on' : 'off'}`,
+        // THE UPDATE LINE IS NOT A CONDITION, and that is the ruling of 2026-09-19 rather than an
+        // omission. A newer version existing is not a fault: the server is serving correctly, and
+        // this file's own header carries the operator's reason — a footer on every result is
+        // noise, noise trains the reader to stop reading. So this never flips line 1, never enters
+        // `degradedConditions`, and never rides another tool's reply. It also means the record is
+        // opened ONLY here, when someone asked for a report, and not on the per-call path whose
+        // cost `docs/status.md` documents.
+        //
+        // `updatecheck` opens one file and asks nobody anything. It is imported instead of
+        // `selfupdate.js` deliberately: `test/selfupdate.test.mjs` pins that `cli.ts` is the ONLY
+        // module in `src/` reaching the one `fetch` in this runtime, and this file is on a path a
+        // host reaches. The version is the one line 2 already printed.
+        updateLine(identity.get('version')),
     ];
     if (conditions.length > 0) {
         lines.push(`${plural(conditions.length, 'problem')}:`);

package/dist/selfupdate.d.ts

@@ -278,19 +278,28 @@ export interface KeptInstall {
  */
 export declare function keptInstall(prefix?: string): KeptInstall | null;
 /**
- * The whole flag: ask the index, compare, and act — or refuse, by name.
- *
- * THE TWO SEAMS ARE `fetch` AND `installer`, and they are options with real defaults rather
- * than module bindings a test rewrites. A test that reached the registry would fail on a plane
- * and pass for the wrong reason off a cache; a test that ran a real installer would rewrite the
- * developer's own `node_modules` mid-suite. Both substitutes are handed in here, so every arm
- * below is reachable offline and the npm command is CAPTURED, never run.
- *
- * THE INDEX IS ASKED BEFORE THE SHAPE IS JUDGED, and that order is the reference's and is
- * deliberate. The user asked the flag to go and check the latest version; an operator on a
- * checkout five releases behind is owed that number even though this flag will not be the thing
- * that installs it. The shape decides the ACTION, never whether the question is asked.
+ * Put the version this flag just fetched into the record `bantamkit_status` reads.
+ *
+ * THE PORT OF `selfupdate.record_update`. Its docstring carries the argument and is not
+ * restated: no second network call and no new failure mode (`update` already holds `latest`),
+ * no directory is ever created, the other runtime's key is left exactly as found, and the
+ * write goes through a temp file and a rename so no reader sees half a record.
+ *
+ * WHY THE WRITER IS HERE AND NOT IN `updatecheck.ts`. That module is the READER, and
+ * `test/updatecheck.test.mjs` gates its source against `writeFileSync`, `renameSync`,
+ * `mkdirSync` and the rest by name — the same claim `test_updatecheck.py` makes over the
+ * reference's AST. The split is structural on both sides, so a future reader cannot grow a
+ * write by accident. `updatecheck.js` is imported here for the PATH and the KEY, which is the
+ * direction that keeps one spelling of each.
+ *
+ * `renameSync` is atomic on POSIX and on Windows, and the temp file is made in the SAME
+ * directory so the rename is never across a filesystem.
+ *
+ * RETURNS whether it wrote, and THROWS FOR NOTHING. A failed write must not turn a successful
+ * `--update` into a failure: the operator's install was updated either way, and the worst case
+ * is a status line that still says `never checked`.
  */
+export declare function recordUpdate(latest: string, now?: string): boolean;
 export declare function update(installed: string, origin: Origin, options?: UpdateOptions): Promise<string>;
 /**
  * `--update` on the CLI: ask the package index, act on the answer, print what happened, exit.

package/dist/selfupdate.js

@@ -40,11 +40,12 @@
  * `test/selfupdate.test.mjs` — and it calls `runUpdate` from the flag and returns before a
  * memory store or a transport exists, the same shape `--assets-root` and `--install` use.
  */
-import { readFileSync } from 'node:fs';
+import { readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { currentInstall, Undetermined } from './mcp/identity.js';
 import { compareVersions, keptCli, keptManifest, keptPrefix, PACKAGE, runInstaller, shlexJoin } from './npminstall.js';
+import { KEY as RECORD_KEY, loadRecord, recordPath, SOURCE_RECORD } from './updatecheck.js';
 // `PACKAGE`, `shlexJoin` and `runInstaller` moved to `npminstall.ts` in job51 so `--install` can
 // share the npm spawner without importing this module (see that file's header). Re-exported so
 // this module's surface — and every test importing these from `dist/selfupdate.js` — is unchanged.
@@ -404,6 +405,71 @@ export function keptInstall(prefix = keptPrefix()) {
  * checkout five releases behind is owed that number even though this flag will not be the thing
  * that installs it. The shape decides the ACTION, never whether the question is asked.
  */
+/**
+ * The `checked_at` stamp's shape, spelled rather than defaulted.
+ *
+ * `toISOString()` renders `.000Z` and CPython's `isoformat()` renders `+00:00`, so a record
+ * written by the two runtimes would differ in bytes neither reader cares about. The reference
+ * formats `%Y-%m-%dT%H:%M:%SZ`; this strips the milliseconds to reach the same shape.
+ */
+function stamp() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+/**
+ * Put the version this flag just fetched into the record `bantamkit_status` reads.
+ *
+ * THE PORT OF `selfupdate.record_update`. Its docstring carries the argument and is not
+ * restated: no second network call and no new failure mode (`update` already holds `latest`),
+ * no directory is ever created, the other runtime's key is left exactly as found, and the
+ * write goes through a temp file and a rename so no reader sees half a record.
+ *
+ * WHY THE WRITER IS HERE AND NOT IN `updatecheck.ts`. That module is the READER, and
+ * `test/updatecheck.test.mjs` gates its source against `writeFileSync`, `renameSync`,
+ * `mkdirSync` and the rest by name — the same claim `test_updatecheck.py` makes over the
+ * reference's AST. The split is structural on both sides, so a future reader cannot grow a
+ * write by accident. `updatecheck.js` is imported here for the PATH and the KEY, which is the
+ * direction that keeps one spelling of each.
+ *
+ * `renameSync` is atomic on POSIX and on Windows, and the temp file is made in the SAME
+ * directory so the rename is never across a filesystem.
+ *
+ * RETURNS whether it wrote, and THROWS FOR NOTHING. A failed write must not turn a successful
+ * `--update` into a failure: the operator's install was updated either way, and the worst case
+ * is a status line that still says `never checked`.
+ */
+export function recordUpdate(latest, now) {
+    const path = recordPath();
+    const directory = dirname(path);
+    try {
+        if (!statSync(directory).isDirectory())
+            return false;
+    }
+    catch {
+        // No `<homedir>/.bantamkit` at all: an install makes that directory, and `--update` does
+        // not get to decide where this toolbox's home lives. Writing nothing is the answer.
+        return false;
+    }
+    const { source, record } = loadRecord(path);
+    // An UNREADABLE record is replaced rather than merged: there is nothing in it to preserve.
+    const payload = source === SOURCE_RECORD && record !== null ? { ...record } : {};
+    payload['checked_at'] = now ?? stamp();
+    payload[RECORD_KEY] = { package: PACKAGE, latest };
+    const temporary = join(directory, `.update-check-${process.pid}-${Date.now()}.json`);
+    try {
+        writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+        renameSync(temporary, path);
+    }
+    catch {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            /* the temp file never existed, or is already gone: either way there is nothing to do */
+        }
+        return false;
+    }
+    return true;
+}
 export async function update(installed, origin, options = {}) {
     const ask = options.fetch ?? fetchIndex;
     const installer = options.installer ?? runInstaller;
@@ -426,6 +492,13 @@ export async function update(installed, origin, options = {}) {
         throw e;
     }
     const latest = latestFromIndexPayload(body);
+    // THE RECORD IS WRITTEN HERE AND NOT IN ONE OF THE ARMS BELOW, because what it records is
+    // "the index said X on this date" — which is true the moment the fetch returned, whatever
+    // this flag then decides to do about it. An operator whose shape has no route gets the
+    // refusal AND a `bantamkit_status` that now knows the number; one who is already current
+    // gets a line that says so with a date. The return value is deliberately dropped: a record
+    // that could not be written is not a reason to fail an update that worked.
+    recordUpdate(latest);
     const header = fill(COMPARISON, { program: PROGRAM, installed, latest });
     const order = compareVersions(installed, latest);
     if (order === 0)

package/dist/updatecheck.d.ts

@@ -0,0 +1,118 @@
+import { compareVersions } from './npminstall.js';
+export { compareVersions };
+/**
+ * The command the operator types — the one word that is true on npm and on PyPI both.
+ *
+ * Equal to `selfupdate.PROGRAM` by construction and by a test, never by an import: see the
+ * module docstring. A sentence naming a PACKAGE could not be byte-identical across runtimes,
+ * because the PyPI distribution is `bantamkit` and the npm package is `bantamkit-mcp`.
+ */
+export declare const PROGRAM = "bantamkit-mcp";
+/**
+ * The key of the record THIS runtime reads. Divergent by construction: the reference reads
+ * `pypi`. Registered as a `docs/porting.md` divergence row by J57-5.
+ */
+export declare const KEY = "npm";
+/**
+ * The two path components, spelled once. `.bantamkit` under a HOME is this toolbox's own
+ * directory; `.bantamkit` under a cwd is a memory store, and this module never builds one.
+ */
+export declare const RECORD_DIR = ".bantamkit";
+export declare const RECORD_NAME = "update-check.json";
+/**
+ * No record at all. The state of a machine that has never been checked and of one that has
+ * been offline since it was installed — deliberately the same state, because they are the same
+ * fact about what is known.
+ */
+export declare const UPDATE_NEVER = "update: never checked.";
+/**
+ * The whole point of the feature. `{latest}` and `{installed}` are BOTH here so the reader can
+ * falsify the claim, the same reason `selfupdate.COMPARISON` carries both.
+ */
+export declare const UPDATE_AVAILABLE: string;
+/** Names the date because the record may be months old. */
+export declare const UPDATE_CURRENT = "update: {program} {installed} is current as of {date}.";
+/**
+ * A real state, not a curiosity: a checkout build, or a release not yet published, lands here —
+ * the same pair `selfupdate.AHEAD` exists for.
+ */
+export declare const UPDATE_AHEAD = "update: {program} {installed} is ahead of the package index, which has {latest}.";
+/**
+ * One sentence for every malformed shape. It does not name WHICH shape: the operator cannot act
+ * differently on any of them, and a per-shape sentence would be N more strings to port.
+ */
+export declare const UPDATE_UNREADABLE = "update: the update record could not be read.";
+export declare const STATE_NEVER = "never";
+export declare const STATE_AVAILABLE = "available";
+export declare const STATE_CURRENT = "current";
+export declare const STATE_AHEAD = "ahead";
+export declare const STATE_UNREADABLE = "unreadable";
+export declare const STATES: readonly ["never", "available", "current", "ahead", "unreadable"];
+/** One of the five above. */
+export type State = (typeof STATES)[number];
+export declare const SOURCE_ABSENT = "absent";
+export declare const SOURCE_UNREADABLE = "unreadable";
+export declare const SOURCE_RECORD = "record";
+/** One of the three above. */
+export type Source = typeof SOURCE_ABSENT | typeof SOURCE_UNREADABLE | typeof SOURCE_RECORD;
+/**
+ * Which of the five states, and the one line that says so.
+ *
+ * Both halves are returned because the conformance gate needs the STATE (the bit that must not
+ * differ between runtimes) while `bantamkit_status` needs the LINE (the bit an operator reads).
+ * Deriving either from the other would be a second decision somewhere.
+ */
+export interface UpdateStatus {
+    state: State;
+    line: string;
+}
+/** What `loadRecord` found, and the record if it found one. */
+export interface LoadedRecord {
+    source: Source;
+    record: Record<string, unknown> | null;
+}
+/**
+ * `<homedir>/.bantamkit/update-check.json`. Never relative to a cwd.
+ *
+ * `homedir()` reads the environment on every call on every platform this ships to — `HOME` on
+ * POSIX, `USERPROFILE` on Windows — which is both the seam the tests use and the reason the
+ * path cannot follow a cwd. `.bantamkit` relative to a cwd is a MEMORY STORE, and creating one
+ * by accident is a defect class this repo has already paid for (J54-3, `hostinstall.ts:362`).
+ *
+ * Returns a path whether or not anything is at it. Nothing here creates either component.
+ */
+export declare function recordPath(home?: string): string;
+/**
+ * What is at the path, and what it holds. Opens one file, creates nothing, and never throws.
+ *
+ * `ENOENT` and `ENOTDIR` are ABSENT — in both, nothing is at the path, and a `.bantamkit` that
+ * is a regular file leaves the operator in exactly the position of one who has never been
+ * checked. Every other error (a directory where the record should be, a mode that cannot be
+ * read) is UNREADABLE, because something IS there and this reader cannot use it. Undecodable
+ * bytes, text that is not JSON, and JSON that is not an object are UNREADABLE for the same
+ * reason.
+ */
+export declare function loadRecord(path?: string): LoadedRecord;
+/**
+ * The parsed record, or `null` when there is not one. Creates nothing, never throws.
+ *
+ * `null` deliberately does NOT say which of absent-or-unreadable it was — a caller that needs
+ * the difference calls `loadRecord`, which is the one this module's own decision uses. This is
+ * the convenience surface for a caller that only wants the object.
+ */
+export declare function readRecord(path?: string): Record<string, unknown> | null;
+/**
+ * The five-state decision, pure: no filesystem, no clock, no network, no TTL.
+ *
+ * Split from the reading so the conformance harness and the tests can construct a state
+ * directly and so the only thing that touches a disk is `loadRecord`.
+ *
+ * `checked_at` is validated in EVERY arm that reached a record and not only on the `current`
+ * path: a record that cannot say when it was written is not a record, and one rule is one thing
+ * for the two runtimes to reproduce instead of two.
+ */
+export declare function decide(installed: string, source: Source, record: Record<string, unknown> | null, key?: string): UpdateStatus;
+/** Read the record and decide. The whole reader, in one call, for `bantamkit_status`. */
+export declare function updateStatus(installed: string, key?: string, path?: string): UpdateStatus;
+/** Exactly one of the five sentences. Always a line: there is no silent state here. */
+export declare function updateLine(installed: string, key?: string, path?: string): string;

package/dist/updatecheck.js

@@ -0,0 +1,278 @@
+/**
+ * The update record on disk, and the five-state line `bantamkit_status` prints from it.
+ *
+ * THE PORT OF `runtime-py/src/bantamkit/updatecheck.py`, AND THE SENTENCES ARE COPIED FROM IT
+ * BYTE FOR BYTE. That module's docstring carries the whole argument — why no reader here may
+ * reach the network (`selfupdate.py:29-31`, measured: one registry GET is 1.5x to 100x an
+ * entire 0.09 s cold stdio boot), why a newer version existing is NOT a degraded condition,
+ * why there is NO TTL in a reader, and why the date is sliced rather than rendered. It is not
+ * restated here; read it there. What belongs HERE is the part that could not be copied.
+ *
+ * EXACTLY ONE THING DIFFERS FROM THE REFERENCE, and it is a genuinely different object rather
+ * than a different spelling of one: `KEY` is `npm` here and `pypi` there, because npm and
+ * PyPI are two registries that can disagree at one version number — job56 shipped a record
+ * that day where they did. The record carries both, each runtime reads its own, and the split
+ * is the `docs/porting.md` divergence row J57-5 registers, the same genuinely-different-object
+ * as `--update`'s URL row.
+ *
+ * `PROGRAM` IS DECLARED HERE RATHER THAN IMPORTED, AND THAT IS NOT A SECOND SOURCE OF TRUTH.
+ * `test/selfupdate.test.mjs` pins that `cli.ts` is the ONLY module in `src/` importing
+ * `selfupdate.ts` — the structural half of AS-7(b), which says a dependency-free toolbox must
+ * not grow a network call on a path a host reaches. This module is reached by
+ * `bantamkit_status`, which is exactly such a path, so importing the module that owns the one
+ * `fetch` in this runtime would break that gate for a five-word constant. The equality is
+ * pinned in `test/updatecheck.test.mjs` instead, where importing both is free, the way the
+ * reference pins `updatecheck.PROGRAM is selfupdate.PROGRAM`.
+ *
+ * `compareVersions` IS IMPORTED, because ordering is the part that can be WRONG. It comes from
+ * `npminstall.ts`, which is where it lives and which `selfupdate.ts` re-exports rather than
+ * owns — so this is the same function the flag uses, not a copy that agrees today. There is no
+ * second comparator in this codebase and this module does not add one; `0.9.0` against
+ * `0.10.0` is the pair that says so, and `test/updatecheck.test.mjs` both runs it and pins
+ * structurally that nothing comparator-shaped is defined here.
+ *
+ * NO NEW DEPENDENCY: `node:fs`, `node:os` and `node:path`. The `str.format` substitution the
+ * reference gets from CPython is the four lines of `fill` below — `selfupdate.ts` has the same
+ * four and cannot be imported for them, for the reason two paragraphs up.
+ *
+ * Layer 5 (Composition): this module reads one file off the operator's home directory and
+ * exists to be called from `mcp/status.ts`. It imports no MCP surface and reaches no network.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { compareVersions } from './npminstall.js';
+export { compareVersions };
+/**
+ * The command the operator types — the one word that is true on npm and on PyPI both.
+ *
+ * Equal to `selfupdate.PROGRAM` by construction and by a test, never by an import: see the
+ * module docstring. A sentence naming a PACKAGE could not be byte-identical across runtimes,
+ * because the PyPI distribution is `bantamkit` and the npm package is `bantamkit-mcp`.
+ */
+export const PROGRAM = 'bantamkit-mcp';
+/**
+ * The key of the record THIS runtime reads. Divergent by construction: the reference reads
+ * `pypi`. Registered as a `docs/porting.md` divergence row by J57-5.
+ */
+export const KEY = 'npm';
+/**
+ * The two path components, spelled once. `.bantamkit` under a HOME is this toolbox's own
+ * directory; `.bantamkit` under a cwd is a memory store, and this module never builds one.
+ */
+export const RECORD_DIR = '.bantamkit';
+export const RECORD_NAME = 'update-check.json';
+// --- the sentences ------------------------------------------------------------------------
+// Copied from `runtime-py/src/bantamkit/updatecheck.py` byte for byte. Changing one is a
+// change to both runtimes and to the conformance suite, never to this file alone.
+/**
+ * No record at all. The state of a machine that has never been checked and of one that has
+ * been offline since it was installed — deliberately the same state, because they are the same
+ * fact about what is known.
+ */
+export const UPDATE_NEVER = 'update: never checked.';
+/**
+ * The whole point of the feature. `{latest}` and `{installed}` are BOTH here so the reader can
+ * falsify the claim, the same reason `selfupdate.COMPARISON` carries both.
+ */
+export const UPDATE_AVAILABLE = 'update: {program} {installed} is running; the package index has {latest} — run ' +
+    '`{program} --update`, then reconnect the host.';
+/** Names the date because the record may be months old. */
+export const UPDATE_CURRENT = 'update: {program} {installed} is current as of {date}.';
+/**
+ * A real state, not a curiosity: a checkout build, or a release not yet published, lands here —
+ * the same pair `selfupdate.AHEAD` exists for.
+ */
+export const UPDATE_AHEAD = 'update: {program} {installed} is ahead of the package index, which has {latest}.';
+/**
+ * One sentence for every malformed shape. It does not name WHICH shape: the operator cannot act
+ * differently on any of them, and a per-shape sentence would be N more strings to port.
+ */
+export const UPDATE_UNREADABLE = 'update: the update record could not be read.';
+// --- the states ----------------------------------------------------------------------------
+// The names are what the non-ruled conformance companion compares: given one record and one
+// running version, both runtimes must land in the SAME state, whichever key each one read.
+export const STATE_NEVER = 'never';
+export const STATE_AVAILABLE = 'available';
+export const STATE_CURRENT = 'current';
+export const STATE_AHEAD = 'ahead';
+export const STATE_UNREADABLE = 'unreadable';
+export const STATES = [
+    STATE_NEVER,
+    STATE_AVAILABLE,
+    STATE_CURRENT,
+    STATE_AHEAD,
+    STATE_UNREADABLE,
+];
+// --- what the loader found -------------------------------------------------------------------
+// Three outcomes and not two, because "there is no file" and "there is a file I cannot read" are
+// different sentences. Collapsing them would print `never checked` over a corrupted record,
+// which is the one wrong thing a reader of this file can do.
+export const SOURCE_ABSENT = 'absent';
+export const SOURCE_UNREADABLE = 'unreadable';
+export const SOURCE_RECORD = 'record';
+/**
+ * `0.36.0`, and `0.31.0rc1` too — a first component of digits and dotted parts after it.
+ * NOT a PEP 440 or semver parse: a parser is a second, larger thing for two runtimes to
+ * reproduce exactly, in service of strings neither writer can produce. `v1.2.3` and `nightly`
+ * are not versions here, and neither registry serves either.
+ */
+const VERSION = /^[0-9]+(?:\.[0-9A-Za-z_+-]+)*$/;
+/**
+ * The `YYYY-MM-DD` prefix, and only the prefix. Whatever follows it is the writer's business:
+ * this module never renders a date, it slices one. A rendered date would make the two runtimes
+ * disagree on a machine set to another locale.
+ */
+const DATE_PREFIX = /^([0-9]{4}-[0-9]{2}-[0-9]{2})/;
+/**
+ * UTF-8, STRICTLY. `readFileSync(path, 'utf8')` would substitute U+FFFD for an undecodable
+ * byte and hand this module a string the reference raises on, so a half-written record would be
+ * a different state on the two sides. Decoding the bytes with `fatal` makes it the same one.
+ *
+ * `ignoreBOM` IS LEFT AT ITS DEFAULT OF `false`, WHICH STRIPS A LEADING BOM, AND THAT IS LOAD
+ * BEARING. The reference reads with `utf-8-sig` for exactly this reason: PowerShell's
+ * `Set-Content` and `Out-File` write UTF-8 WITH a BOM by default, and a record a reader can
+ * plainly act on is not "a shape this reader cannot act on". Setting `ignoreBOM: true` here
+ * would leave the BOM in the string, `JSON.parse` would refuse it, and this side would call a
+ * Windows operator's perfectly good record broken. The BOM arms in
+ * `tools/conformance/suites/updatecheck.mjs` are what hold the two sides together on it; it is
+ * NOT a `docs/porting.md` divergence, because there is no difference left to register.
+ */
+const UTF8 = new TextDecoder('utf-8', { fatal: true });
+/**
+ * `{name}` substitution, the four lines of `str.format` these sentences use.
+ *
+ * `selfupdate.ts` exports the same function and this module may not import it (see the module
+ * docstring). Kept to exactly the braces the five sentences carry: a missing key is left alone
+ * rather than rendered as `undefined`, which is what makes a typo visible instead of silent.
+ */
+function fill(template, values) {
+    return template.replace(/\{([a-z]+)\}/g, (whole, name) => values[name] ?? whole);
+}
+/**
+ * `<homedir>/.bantamkit/update-check.json`. Never relative to a cwd.
+ *
+ * `homedir()` reads the environment on every call on every platform this ships to — `HOME` on
+ * POSIX, `USERPROFILE` on Windows — which is both the seam the tests use and the reason the
+ * path cannot follow a cwd. `.bantamkit` relative to a cwd is a MEMORY STORE, and creating one
+ * by accident is a defect class this repo has already paid for (J54-3, `hostinstall.ts:362`).
+ *
+ * Returns a path whether or not anything is at it. Nothing here creates either component.
+ */
+export function recordPath(home = homedir()) {
+    return join(home, RECORD_DIR, RECORD_NAME);
+}
+/**
+ * What is at the path, and what it holds. Opens one file, creates nothing, and never throws.
+ *
+ * `ENOENT` and `ENOTDIR` are ABSENT — in both, nothing is at the path, and a `.bantamkit` that
+ * is a regular file leaves the operator in exactly the position of one who has never been
+ * checked. Every other error (a directory where the record should be, a mode that cannot be
+ * read) is UNREADABLE, because something IS there and this reader cannot use it. Undecodable
+ * bytes, text that is not JSON, and JSON that is not an object are UNREADABLE for the same
+ * reason.
+ */
+export function loadRecord(path = recordPath()) {
+    let text;
+    try {
+        text = UTF8.decode(readFileSync(path));
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return { source: SOURCE_ABSENT, record: null };
+        // Everything else is a state, not an exception: `EISDIR`, `EACCES`, and the `TypeError`
+        // a fatal `TextDecoder` throws on bytes that are not UTF-8.
+        return { source: SOURCE_UNREADABLE, record: null };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        return { source: SOURCE_UNREADABLE, record: null };
+    }
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        // A list or a bare number is well-formed JSON and is not a record. `typeof null` is
+        // `'object'` in JavaScript and `null` is not a record either.
+        return { source: SOURCE_UNREADABLE, record: null };
+    }
+    return { source: SOURCE_RECORD, record: payload };
+}
+/**
+ * The parsed record, or `null` when there is not one. Creates nothing, never throws.
+ *
+ * `null` deliberately does NOT say which of absent-or-unreadable it was — a caller that needs
+ * the difference calls `loadRecord`, which is the one this module's own decision uses. This is
+ * the convenience surface for a caller that only wants the object.
+ */
+export function readRecord(path = recordPath()) {
+    return loadRecord(path).record;
+}
+/** `record[key].latest` when it is a version string, else `null`. Throws for nothing. */
+function latestIn(record, key) {
+    const entry = record[key];
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry))
+        return null;
+    const latest = entry['latest'];
+    if (typeof latest !== 'string')
+        return null;
+    const trimmed = latest.trim();
+    return VERSION.test(trimmed) ? trimmed : null;
+}
+/** The `YYYY-MM-DD` prefix of `checked_at`, or `null`. Sliced, never rendered. */
+function checkedDate(record) {
+    const checkedAt = record['checked_at'];
+    if (typeof checkedAt !== 'string')
+        return null;
+    const found = DATE_PREFIX.exec(checkedAt.trim());
+    return found?.[1] ?? null;
+}
+/**
+ * The five-state decision, pure: no filesystem, no clock, no network, no TTL.
+ *
+ * Split from the reading so the conformance harness and the tests can construct a state
+ * directly and so the only thing that touches a disk is `loadRecord`.
+ *
+ * `checked_at` is validated in EVERY arm that reached a record and not only on the `current`
+ * path: a record that cannot say when it was written is not a record, and one rule is one thing
+ * for the two runtimes to reproduce instead of two.
+ */
+export function decide(installed, source, record, key = KEY) {
+    if (source === SOURCE_ABSENT)
+        return { state: STATE_NEVER, line: UPDATE_NEVER };
+    if (source !== SOURCE_RECORD || record === null) {
+        return { state: STATE_UNREADABLE, line: UPDATE_UNREADABLE };
+    }
+    const date = checkedDate(record);
+    const latest = latestIn(record, key);
+    if (date === null || latest === null) {
+        return { state: STATE_UNREADABLE, line: UPDATE_UNREADABLE };
+    }
+    const order = compareVersions(installed, latest);
+    if (order < 0) {
+        return {
+            state: STATE_AVAILABLE,
+            line: fill(UPDATE_AVAILABLE, { program: PROGRAM, installed, latest }),
+        };
+    }
+    if (order === 0) {
+        return {
+            state: STATE_CURRENT,
+            line: fill(UPDATE_CURRENT, { program: PROGRAM, installed, date }),
+        };
+    }
+    return {
+        state: STATE_AHEAD,
+        line: fill(UPDATE_AHEAD, { program: PROGRAM, installed, latest }),
+    };
+}
+/** Read the record and decide. The whole reader, in one call, for `bantamkit_status`. */
+export function updateStatus(installed, key = KEY, path = recordPath()) {
+    const { source, record } = loadRecord(path);
+    return decide(installed, source, record, key);
+}
+/** Exactly one of the five sentences. Always a line: there is no silent state here. */
+export function updateLine(installed, key = KEY, path = recordPath()) {
+    return updateStatus(installed, key, path).line;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bantamkit-mcp",
-  "version": "0.35.1",
+  "version": "0.35.2",
   "description": "Memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop: per-person memory, JSON Schema validation, shift-work tools. Pure Node; install once with npx, run offline.",
   "keywords": [
     "mcp",