bantamkit 0.32.0__tar.gz → 0.32.1__tar.gz

{bantamkit-0.32.0 → bantamkit-0.32.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bantamkit
-Version: 0.32.0
+Version: 0.32.1
 Summary: bantamweight tooling — harness primitives that lift small-model agents
 License-Expression: MIT
 Requires-Python: >=3.11

{bantamkit-0.32.0 → bantamkit-0.32.1}/src/bantamkit/__init__.py

@@ -29,4 +29,4 @@ from bantamkit.structured import StructuredOutputError, extract_json, structured
 # file as its dynamic version source, so the wheel's metadata and the string the MCP
 # server advertises are the same committed bytes, and neither is a function of when
 # someone last ran `pip`.
-__version__ = "0.32.0"
+__version__ = "0.32.1"

{bantamkit-0.32.0 → bantamkit-0.32.1}/src/bantamkit/mcpserver.py

@@ -8,6 +8,7 @@ import hashlib
 import json
 import os
 import platform
+import stat as stat_module
 import sys
 from collections.abc import Callable, Iterable, Iterator
 from contextlib import contextmanager
@@ -2042,10 +2043,80 @@ def _build_memory(args: argparse.Namespace) -> Memory:
     if args.store is not None:
         if not args.store:
             raise SystemExit("--store requires a non-empty path")
+        _check_store_flag(args.store)
         return Memory(store=args.store, k=args.k, index_budget=args.index_budget)
     return Memory.layered(start=args.start, k=args.k, index_budget=args.index_budget)
 
 
+def _check_store_flag(raw: str) -> None:
+    """`--store` may name a store that is missing, never one that is not a store.
+
+    THIS CHECK IS RESTORED, NOT INVENTED, and the distinction is the point. Until the
+    project layer was built lazily there WAS a `--store` validation, and it was entirely
+    accidental: the constructor ran `mkdir(parents=True)`, so a `--store` pointing at a
+    regular file or at a path under a directory that does not exist took the process down
+    with an `OSError` traceback out of `pathlib`. `test_statusline.py::
+    test_the_flag_returns_before_anything_a_server_would_touch` depends on it -- it arms
+    `--store <a regular file>` as a trap and shows `--statusline` walking past it -- and a
+    lazy layer disarms the trap by making that same argv exit 0. The honest way to keep
+    that test true is to mean the refusal on purpose.
+
+    IT IS `layers._pinned_store`'s CHECK MINUS ONE ARM, and the missing arm is deliberate
+    and measured. The pin refuses a path that is not there ("nothing was created"); this
+    flag does NOT, and must not, for two reasons that are both already pinned elsewhere in
+    this repository:
+
+    - The sibling CLI's identical flag is contracted to CREATE one. `tools/conformance/
+      suites/memorycli.mjs` carries `status-creates-a-missing-store`, `--store {BED}/nowhere`
+      over an empty bed, whose whole job is to say the two runtimes create the same two
+      directories there. Refusing a missing `--store` here would put two flags of the same
+      name, in two programs of the same product, in direct contradiction.
+    - "Missing" is no longer a broken state anywhere in this program. The walk designates a
+      project store without creating it, and the first save brings it into existence or
+      refuses by name (`store._ensure_dirs`). A `--store` at a path that is not there is
+      that same designated state, reached by being told instead of by searching. MEASURED:
+      requiring existence here reddened 14 tests that have nothing to do with this defect
+      -- `test_tool_manifest.py` ×7, `test_mcpserver.py` ×6, `test_mcp_endpoint.py` -- every
+      one of them a fixture naming a store under `tmp_path` it never made, because that is
+      what this flag has always meant.
+
+    What is left is the arm the accident actually covered and the only one it covered: a
+    `--store` that names something which EXISTS and is NOT A DIRECTORY. That is not a store
+    and never becomes one -- `mkdir` under it is ENOTDIR on both runtimes and on every
+    platform, the one row of the errno table where they already agree -- so it is refused
+    here, by name, before a transport exists.
+
+    `FileNotFoundError` and not an errno comparison: the absent case is selected by the
+    exception CPython raises for it, which `runtime-ts`' `pyfs` shim raises under the same
+    name. Every other `stat` failure -- a permission wall on the parent, a symlink loop --
+    is a real fault about a path the operator named, and it keeps the pin's sentence.
+
+    `os.stat` rather than `Path.is_dir()`, and that too is `_pinned_store`'s reasoning:
+    `is_dir()` swallows `PermissionError` and answers False, which would report an
+    operator's real store as a typo. A single named path gets the accurate reason.
+
+    `SystemExit` and not `MemoryValidationError`, so that both halves of this flag's
+    refusal family read the same way on the terminal: `--store requires a non-empty path`
+    is already bare on stderr at exit 1, and the port spells both as `Refusal`.
+    """
+    # NOT `expanduser()`, unlike the pin. `Memory(store=...)` builds `Path(root)` from this
+    # string verbatim, so expanding here would check one path and serve another: `--store
+    # ~/x` left unexpanded by the shell would pass a check against the home directory and
+    # then build a store in a directory literally named `~`. The check must stat the path
+    # the store is going to be.
+    store = Path(raw)
+    try:
+        info = os.stat(store)
+    except FileNotFoundError:
+        return  # designated, not broken: the first save makes it or refuses by name
+    except OSError as e:
+        raise SystemExit(
+            f"--store is unreachable: {store}: {e.strerror}; nothing was created"
+        ) from e
+    if not stat_module.S_ISDIR(info.st_mode):
+        raise SystemExit(f"--store is not a directory: {store}")
+
+
 def _print_mcp_report(args: argparse.Namespace) -> None:
     """`--mcp-report`: the joined report on stdout, then return. No transport, no server.
 
@@ -2184,9 +2255,43 @@ def _refuse_update(sentence: str) -> NoReturn:
 
 
 def main() -> None:
+    """Dispatch one invocation, and hand a refusal to the operator as a SENTENCE.
+
+    THIS ARM IS A PARITY DEFECT BEING CLOSED, not a nicety. `runtime-ts/src/cli.ts` has
+    caught `BantamError` at its top level and written `bantamkit-mcp: <message>` at exit 1
+    since it was written, and `bantamkit/memory/__main__.py` was handed the same defect and
+    fixed the same way for the operator memory CLI. This CLI never got it, so the identical
+    refusal -- `BANTAMKIT_MEMORY_DIR=/nope/pinned`, one sentence that already names the
+    directory and says nothing was created -- was one clean line on Node and a two-stage
+    CPython traceback on Python, carrying this repository's absolute paths and line numbers
+    in place of the store the operator asked about. Nothing covered it, so the suite was
+    green over it.
+
+    `BantamError` AND NOTHING WIDER, in `__main__.py`'s own words: a bug in bantamkit is
+    still a traceback, because that one IS a report for a maintainer. What is caught is the
+    class of failures that are ABOUT the operator's store, and every one of them already
+    carries a sentence that names the directory and says what the consequence would have
+    been -- including `_ensure_dirs`' new one, which is the whole reason a cwd of `/` is now
+    a refused write rather than a dead process.
+
+    `SystemExit` is deliberately not caught: argparse's usage errors are exit 2, and this
+    file's own flag refusals are already their own sentence on stderr.
+
+    Written through `sys.stderr.buffer`, like every other refusal in this file, so the line
+    ends LF on Windows too and cannot drift from the port's `process.stderr.write`.
+    """
     if MCPServer is None:
         raise SystemExit(_INSTALL_HINT)
     args = _parse_args()
+    try:
+        _dispatch(args)
+    except BantamError as e:
+        sys.stderr.buffer.write(f"bantamkit-mcp: {e}\n".encode())
+        sys.stderr.buffer.flush()
+        raise SystemExit(1) from e
+
+
+def _dispatch(args: argparse.Namespace) -> None:
     # Before `_build_memory`, which touches the filesystem, and before the server exists at
     # all -- the Node arm returns from `main` here too, ahead of `new RawStdioTransport()`.
     if args.assets_root:
@@ -2215,6 +2320,14 @@ def main() -> None:
     # `.bantamkit/memory` directory in whatever cwd they were standing in, and the flags
     # above return before a transport for the same class of reason.
     #
+    # AMENDMENT 2026-09-12 (job48, J48-1). "which is what creates a store" is no longer
+    # true of the sentence's own words: the project layer is built `create=False`, so
+    # `_build_memory` designates a path and creates nothing until a save. The guard stays
+    # exactly where it is, for what remains of the reason -- a person typing a command to
+    # see what it does has not asked for a walk up their filesystem either -- and it stays
+    # because the ORDER is the contract the port shares, not because it is the last thing
+    # standing between a bare invocation and a mkdir.
+    #
     # STDOUT AND EXIT 0, i.e. byte-for-byte what `-h` does on this platform, because the
     # request was "ให้แสดงเหมือน --help" -- show it the way `--help` shows it. `print_help`
     # is the same call argparse's own `-h` action makes, so the two cannot diverge: fix

{bantamkit-0.32.0 → bantamkit-0.32.1}/src/bantamkit/memory/component.py

@@ -184,14 +184,38 @@ class Memory:
         index_budget: int = DEFAULT_INDEX_BUDGET,
         binding: StoreBinding | None = None,
     ):
-        self.store = MemoryStore(store, index_budget=index_budget, k=k)
+        # `create=False`, AND IT IS THE WHOLE OF THE cwd-`/` FIX. This was the last eager
+        # layer -- grants and the profile store have always been lazy -- so a cwd that no
+        # directory can be created under was a STARTUP CRASH: every GUI MCP host launches
+        # its child with cwd `/`, measured live on this machine (`lsof -p <pid> -a -d cwd`
+        # on Claude Desktop and all four of its `bantamkit-mcp` children returns `/`), and
+        # the client saw only CONNECTION_CLOSED. Refusing at startup with a sentence was the
+        # other candidate and it is REFUTED by measurement: it leaves those same four
+        # processes dead, which is strictly worse than today. Built lazily, the server
+        # starts from `/`, binds `['project', 'profile']`, and answers out of the profile
+        # layer. The sentence still exists -- it is what `MemoryStore.save`/`compact` say
+        # when a write actually needs the directory (`store._ensure_dirs`).
+        #
+        # It is legal because every READ is already defined over an absent directory:
+        # `recall() -> []`, `archived() -> []`, `index_text() -> ''`. `_facts`' docstring
+        # says so outright, and `create=False` is one of the three callers it names.
+        #
+        # THE PRICE, stated rather than discovered: a bare server start in a perfectly good
+        # cwd no longer scatters `.bantamkit/memory/{facts,archive}` there before anything
+        # is saved. That moves TOWARD a stance this file already holds -- see the binding
+        # comment below, and `mcpserver.main`'s bare-TTY guard.
+        self.store = MemoryStore(store, index_budget=index_budget, k=k, create=False)
         self.k = k
         self._layers: list[tuple[str, MemoryStore, bool]] = [("project", self.store, True)]
         self._show_layers = False
-        # How this store came to be the store, captured once. It cannot be re-derived
-        # later: `MemoryStore(create=True)` above has already made the directory, so a
-        # store that was only DESIGNATED a moment ago is indistinguishable on disk from
-        # one that was found empty. `None` means the caller named the path outright --
+        # How this store came to be the store, captured once. It is still captured here and
+        # not re-derived later, but the reason has changed with the line above and the old
+        # one is recorded rather than deleted: it WAS that `MemoryStore(create=True)` had
+        # already made the directory, so a store that was only DESIGNATED a moment ago was
+        # indistinguishable on disk from one that was found empty. That complaint is now
+        # discharged -- nothing is created -- and the binding is kept because it also
+        # carries WHY this path (`origin`, `searched_from`), which no amount of looking at
+        # the disk recovers. `None` means the caller named the path outright --
         # `Memory(store=...)` — and no resolution happened to report.
         self._binding = binding
 
@@ -207,8 +231,15 @@ class Memory:
         `resolve_project_store` rather than `discover_project_store`: the path both
         return is the same path (`test_resolve_path_never_disagrees_with_discover`),
         but only the binding carries WHY it is that path and whether it holds
-        anything — and `recall` cannot recover either fact afterwards, because
-        constructing the store creates the directory.
+        anything — and `recall` cannot recover either fact afterwards.
+
+        AMENDMENT 2026-09-12 (job48, J48-1), correcting the reason the clause above used
+        to give and not the clause itself. WAS: "because constructing the store creates
+        the directory." NOW that is false -- the project layer is built `create=False`
+        (see `__init__`) and constructing it creates nothing. The binding is still the
+        only carrier of WHY, because `origin` and `searched_from` were never on the disk
+        to begin with; what the disk has stopped being able to answer is merely "was this
+        empty or brand new", which it now answers correctly for the first time.
         """
         binding = resolve_project_store(start)
         project_root = binding.path
@@ -553,9 +584,20 @@ class Memory:
         if binding is None:
             where = f"The project store {root} is empty."
         elif binding.state == "designated":
+            # AMENDED 2026-09-12 (job48, J48-1) because the sentence became FALSE, not
+            # because it read badly. WAS: "No memory store existed at or above <from>, so
+            # the empty <root> was created for this session." Under a lazily-built project
+            # layer nothing is created -- the path is designated and stays absent until a
+            # save needs it -- so the old sentence told an operator to go look for a
+            # directory that is not there. The new one borrows the pin's own closing
+            # clause, "nothing was created", because it is the same claim about the same
+            # thing, and it reuses the binding's existing `designated` vocabulary rather
+            # than minting a word for it. The remedy that follows -- "otherwise save a
+            # memory to start this one" -- is now literally true: the save is what brings
+            # the directory into existence.
             where = (
-                f"No memory store existed at or above {binding.searched_from}, so the "
-                f"empty {root} was created for this session."
+                f"No memory store existed at or above {binding.searched_from}, so {root} "
+                f"was designated for this session; nothing was created there."
             )
         elif binding.origin == "pin":
             where = f"The project store {root} is empty; {MEMORY_DIR_ENV} pinned it."

{bantamkit-0.32.0 → bantamkit-0.32.1}/src/bantamkit/memory/store.py

@@ -315,8 +315,40 @@ class MemoryStore:
             self._snapshot = previous
 
     def _ensure_dirs(self) -> None:
-        (self.root / "facts").mkdir(parents=True, exist_ok=True)
-        (self.root / "archive").mkdir(parents=True, exist_ok=True)
+        """Bring the store's directories into existence, or refuse the write that needs them.
+
+        THE PROPERTY: a store that cannot be brought into existence cannot be written to,
+        and the refusal names which directory and why. It is a refusal and not a crash
+        because the only callers are the two WRITES (`save`, `compact`); every read is
+        already defined over an absent directory -- `_facts`' own docstring rules it, "AN
+        ABSENT DIRECTORY IS `[]`, NOT AN ERROR" -- which is what makes a lazily-built
+        project layer legal at all.
+
+        THE PREDICATE IS THE OUTCOME AND NEVER AN ERRNO, and that is measured rather than
+        tidy. One cwd, `/`, gives CPython EROFS(30) at `/.bantamkit` and Node ENOENT(-2) at
+        `/.bantamkit/memory/facts`, because Node's recursive mkdir does not pass EROFS
+        through and stats the missing path instead; a `chmod 555` directory gives EACCES(13)
+        on both; and on Linux `/` is a writable root owned by root, so the same cwd gives
+        EACCES there. Three platforms, three numbers, one fact -- the directory could not be
+        made -- so the `except` is the whole of `OSError` and the sentence carries no errno.
+        A fix keyed on the number would have been green on Linux CI and wrong on the machine
+        the bug was reported from.
+
+        THE SENTENCE NAMES `self.root` AND NOTHING DEEPER, for the same reason. The two
+        runtimes fail at different components of the same path (`/.bantamkit` against
+        `/.bantamkit/memory/facts`) and report different strerrors for it, so a sentence
+        carrying the failing leaf, or that strerror, would be a divergence manufactured by
+        mkdir's internals. `self.root` is the path the caller named and both sides agree on
+        it, which is what lets one conformance case pin this line byte for byte.
+        """
+        try:
+            (self.root / "facts").mkdir(parents=True, exist_ok=True)
+            (self.root / "archive").mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            raise MemoryValidationError(
+                f"memory store could not be created: {self.root}; the directory is not"
+                " there and this filesystem would not make it, so nothing was written"
+            ) from e
 
     # ---- ops ----
 
@@ -542,6 +574,15 @@ class MemoryStore:
         archived by staleness and this loop still lands at or below `target`.
         """
         facts = self._facts()
+        # SECOND, NOT FIRST, and the order is the paragraph above kept intact: the listing
+        # still refuses an unreadable store before anything here moves a file. What this
+        # line adds is the other half of the same stance -- this method WRITES (every
+        # `replace` below lands in `archive/`, and `_rebuild_index` writes `index.md` into
+        # the root whether or not a single fact was archived), so a root that does not
+        # exist and cannot be made is refused here, by name, instead of surfacing as a
+        # `FileNotFoundError` out of the final write. `exist_ok=True` makes it free for
+        # every store that is already there.
+        self._ensure_dirs()
         sizes = {fact.name: len(self._index_line(fact).encode()) for fact in facts}
         if reserve is None:
             # The default reserve is measured from the WARNING LINE, not from the budget.

{bantamkit-0.32.0 → bantamkit-0.32.1}/tests/test_status_surface.py

@@ -54,7 +54,20 @@ def run(coro):
 
 
 def make_memory(tmp_path, **kwargs) -> Memory:
-    return Memory(store=tmp_path / "store", **kwargs)
+    """A `Memory` whose store is ON DISK, because every test below breaks one by hand.
+
+    THE `mkdir` IS THE FIXTURE'S OWN AS OF job48, and it is a fixture change and not a
+    weakened assertion. The project layer is built `create=False` -- a cwd that nothing can
+    be created under must be a refused write and not a startup crash -- so constructing a
+    `Memory` no longer brings `facts/` and `archive/` into existence. The tests here all
+    start from a store that is already there (`_break_the_project_layer` rmtree's `facts/`;
+    the budget helper saves into it), so the directories they were relying on the
+    constructor for are made here instead. Not one assertion below moves.
+    """
+    root = tmp_path / "store"
+    (root / "facts").mkdir(parents=True, exist_ok=True)
+    (root / "archive").mkdir(parents=True, exist_ok=True)
+    return Memory(store=root, **kwargs)
 
 
 def status_of(server) -> str:
@@ -311,8 +324,10 @@ def test_an_unreadable_memory_layer_is_observed_and_named_by_kind_not_by_name(tm
 def test_a_granted_layer_is_reported_by_its_kind_and_never_by_its_grant_name(tmp_path):
     """The sharp case for the metadata rule: `extra:<name>` carries the operator's words."""
     grant = tmp_path / "teamdocs" / ".bantamkit" / "memory"
-    Memory(store=grant)
-    (grant / "facts").rmdir()
+    # Built here rather than by `Memory(store=grant)` for the reason `make_memory` gives:
+    # since job48 constructing a store creates nothing. The on-disk state this test
+    # actually needs is unchanged -- `archive/` a directory, `facts/` a regular file.
+    (grant / "archive").mkdir(parents=True)
     (grant / "facts").write_text("not a directory", encoding="utf-8")
     project_root = tmp_path / "proj"
     (project_root / ".bantamkit" / "memory").mkdir(parents=True)