bantamkit 0.35.6__tar.gz → 0.35.8__tar.gz

{bantamkit-0.35.6 → bantamkit-0.35.8}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: bantamkit
-Version: 0.35.6
+Version: 0.35.8
 Summary: Memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop, plus a Python library that lifts small-model agents. Install once, run offline.
 Project-URL: Homepage, https://github.com/Ink01101011/bantamkit
 Project-URL: Repository, https://github.com/Ink01101011/bantamkit
@@ -103,9 +103,9 @@ CPU architecture and Python minor version** (some wheels, such as `pydantic_core
 one platform only), copy `wheels/` across, and install from it:
 
 ```bash
-python -m pip download "bantamkit[mcp]==0.35.6" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.8" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.6"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.8"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 

{bantamkit-0.35.6 → bantamkit-0.35.8}/README.md

@@ -74,9 +74,9 @@ CPU architecture and Python minor version** (some wheels, such as `pydantic_core
 one platform only), copy `wheels/` across, and install from it:
 
 ```bash
-python -m pip download "bantamkit[mcp]==0.35.6" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.8" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.6"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.8"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 

{bantamkit-0.35.6 → bantamkit-0.35.8}/_assets/tools/memory_compact.json

@@ -10,8 +10,7 @@
     "properties": {
       "reserve": {
         "type": "integer",
-        "minimum": 0,
-        "description": "Bytes of index headroom to free below the budget. Omit for the default: the size of the largest index line the store holds, capped at half the budget."
+        "description": "Bytes of index headroom to free below the budget: the target is `budget - reserve`, a negative value counts as 0, any value is capped at half the budget, and 0 compacts to the budget itself. Omit for the default: the room the degraded-index warning demands (the budget minus `(90 * budget - 1) // 100`) plus the size of the largest index line the store holds -- at the default 24000-byte budget with a 39-byte largest line that is 2401 + 39 = 2440, a 21560-byte target."
       }
     }
   },

{bantamkit-0.35.6 → bantamkit-0.35.8}/_assets/tools/memory_recall.json

@@ -17,9 +17,7 @@
       },
       "k": {
         "type": "integer",
-        "minimum": 1,
-        "maximum": 5,
-        "description": "Facts wanted. Raised to the store default of 3 when smaller; never lowered below it."
+        "description": "Facts wanted, clamped to 1..5. Raised to the store default of 3 when smaller; never lowered below it."
       }
     }
   },

bantamkit-0.35.8/_assets/tools/shiftwork_clock_in.json

@@ -0,0 +1,37 @@
+{
+  "name": "shiftwork_clock_in",
+  "description": "Shift-work clock-in: schema-validate the checkpoint file and return the brief for the unit at plan.cursor — {unit, role, invariants, handoff, do_not, files} — to hand to the spawned agent verbatim. The unit briefed is the one at plan.cursor, or, when unit_id is given, that unit — either way it must appear in shiftwork_plan's `ready`, the batch the dependency graph says may run now: the cursor unit is held to the same ready test as unit_id. A unit that is not ready (a done or dropped cursor, a cursor whose dependencies have not run, a unit_id naming no unit) is refused with {\"result\": \"error\", \"reason\": \"unit <id> is not ready; ready is <a, b>\"}, and on both paths the refusals of the batch view itself (cycle, unknown dependency, unreadable checkpoint) pass through verbatim; a cursor naming no unit still escalates. Clock-in still never moves plan.cursor; clock_out does. Structured refusals, never exceptions: result=escalate when handoff.open_questions is non-empty, result=success when every unit is done or dropped, result=error when the checkpoint fails validation. Clock-in also WRITES: on result=brief, and only then, it appends one line {event: brief, ts, unit, role} to <checkpoint>.log.jsonl — best-effort: a log it cannot write costs the brief nothing (the brief still returns, no error, only the record is lost). clock_out reads those lines back to write `briefed` on every accounting line, so the ledger is no longer one line per clock-out; a brief line carries `event` and no `status`. See docs/shiftwork.md.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      },
+      "unit_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Unit Id"
+      }
+    },
+    "required": [
+      "checkpoint"
+    ],
+    "type": "object",
+    "title": "shiftwork_clock_inArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "shiftwork_clock_inDictOutput"
+  }
+}

{bantamkit-0.35.6 → bantamkit-0.35.8}/_assets/tools/shiftwork_clock_out.json

@@ -87,7 +87,7 @@
         "anyOf": [
           {
             "type": "object",
-            "description": "Per-unit cost. Written verbatim, beside ts/unit/role/status, as one line of <checkpoint>.log.jsonl - the ledger the N-sessions experiment reads. The keys named here have fixed meanings so a reader holding only the ledger knows what each number counts, in which unit, and which model produced it; any other key passes through unchanged (a refused key is friction, not safety). Lines written before this schema existed may spell these differently; the schema governs new writes only.",
+            "description": "Per-unit cost. Written verbatim, beside ts/unit/role/status, as one line of <checkpoint>.log.jsonl - the ledger the N-sessions experiment reads. The keys named here have fixed meanings so a reader holding only the ledger knows what each number counts, in which unit, and which model produced it; any other key passes through unchanged, except the five the runtime writes itself — unit, role, status, ts, event — which are refused (result=error) before anything is written; a self-reported briefed is overwritten, not refused. Lines written before this schema existed may spell these differently; the schema governs new writes only.",
             "properties": {
               "tokens": {
                 "type": "integer",

{bantamkit-0.35.6 → bantamkit-0.35.8}/_assets/tools/validate_json.json

@@ -1,6 +1,6 @@
 {
   "name": "validate_json",
-  "description": "Validate candidate output text against a JSON Schema. Returns {valid, feedback}; when invalid, feed the feedback back to the model and retry.",
+  "description": "Validate candidate output text against a JSON Schema. Returns {valid, feedback}; when invalid, feed the feedback back to the model and retry. The output may be any JSON value; otherwise the first fenced block, or the first object or array in the text, is used. $schema selects draft-04, draft-06, draft-07, 2019-09 or 2020-12 (default); $ref resolves only inside the one schema (\"#\", \"#/...\", \"#name\"), so a remote reference or an embedded $id is refused. pattern is Python re syntax, without inline flags, look-behind, backreferences, atomic or possessive groups, conditional groups or \\N{...}; a document's patterns get 500 ms in total.",
   "surfaces": [
     "mcp"
   ],

bantamkit-0.35.8/_assets/tools/work_plan.json

@@ -0,0 +1,55 @@
+{
+  "name": "work_plan",
+  "description": "Work plan: turn a dependency graph into the batches that may run in parallel. Takes `nodes`, each `{id, depends_on, priority}` — `depends_on` absent or null means none, `priority` defaults to 0 — and answers `{\"result\": \"plan\", \"batches\", \"sequence\", \"width\"}`: batch k holds every node whose dependencies all appear in batches below k, `sequence` is those batches flattened in order, and `width` is the largest batch length — the widest fan-out, which is the number an orchestrator needs to decide whether it can afford the batch. Order inside a batch is priority descending, then the order the nodes were given; both halves are contract, because determinism inside a batch is what two implementations are held to. Empty `nodes` is an ANSWER, not a refusal: no batches, no sequence, width 0. Four refusals, checked in this order and one sentence each: `nodes[<i>].<field> must be ...` for a node whose `id` is not a string, whose `depends_on` is not a list of strings or whose `priority` is not an integer (named by position, never coerced), `duplicate node id <id>`, `node <id> depends on <dep>, which no node declares`, and `the graph has a cycle: <a> -> <b> -> <a>`. It reports what the graph permits and decides nothing about what may actually be dispatched together — `depends_on` encodes logical order, not file contention, so a batch this tool calls parallel may still hold work that writes one file. Pure computation over the nodes it was handed: it opens no file and takes no path. Never mutates.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "nodes": {
+        "title": "Nodes",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "The node's identifier, unique across `nodes`"
+            },
+            "depends_on": {
+              "anyOf": [
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Ids this node waits for; every one of them must be declared by some node. Optional: absent or null means none"
+            },
+            "priority": {
+              "type": "integer",
+              "description": "Tie-break inside a batch, descending. Optional; 0 when absent"
+            }
+          },
+          "required": [
+            "id"
+          ]
+        }
+      }
+    },
+    "required": [
+      "nodes"
+    ],
+    "type": "object",
+    "title": "work_planArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "work_planDictOutput"
+  }
+}

{bantamkit-0.35.6 → bantamkit-0.35.8}/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.35.6"
+__version__ = "0.35.8"

{bantamkit-0.35.6 → bantamkit-0.35.8}/src/bantamkit/contract.py

@@ -2,11 +2,24 @@
 
 from __future__ import annotations
 
+import builtins
+import contextvars
+import importlib
 import json
+import queue
 import re
+import subprocess
+import sys
+import threading
+import time
+from collections.abc import Iterator
+from re import _constants as _sre
+from re import _parser as _sre_parse
 
 import jsonschema
 import yaml
+from jsonschema.exceptions import _WrappedReferencingError
+from referencing.exceptions import NoSuchAnchor, PointerToNowhere
 
 from bantamkit.assets import AssetNotFound, assets_root
 from bantamkit.client import BantamError, Message
@@ -108,11 +121,17 @@ def validation_error_message(where: str, detail: str) -> str:
     return load_contract()["validation_error"].format(where=where, detail=detail)
 
 
-def extract_json(text: str) -> dict | list:
+def _unfenced(text: str) -> str:
+    """The text `extract_json` searches: stripped, and the first fenced block's body if any."""
     text = text.strip()
     fence = re.search(r"```(?:json)?\s*(.*?)```", text, re.DOTALL)
     if fence:
         text = fence.group(1).strip()
+    return text
+
+
+def extract_json(text: str) -> dict | list:
+    text = _unfenced(text)
     start_brace = text.find("{")
     start_bracket = text.find("[")
     if start_brace == -1 and start_bracket == -1:
@@ -127,20 +146,388 @@ def extract_json(text: str) -> dict | list:
     return obj
 
 
+_REF_KEYWORDS = ("$ref", "$dynamicRef", "$recursiveRef")
+# The keywords whose value holds subschemas, in ANY dialect — the walk the pre-scan takes.
+# `runtime-ts/src/pyjsonschema.ts` (`subschemas`) is the same walk in the same order, which
+# is what makes the two refusal sentences name the same place.
+_WALK_SUBSCHEMA = frozenset(
+    {
+        "additionalItems",
+        "additionalProperties",
+        "contains",
+        "else",
+        "if",
+        "items",
+        "not",
+        "propertyNames",
+        "then",
+        "unevaluatedItems",
+        "unevaluatedProperties",
+    }
+)
+_WALK_MAP = frozenset(
+    {"$defs", "definitions", "dependencies", "dependentSchemas", "patternProperties", "properties"}
+)
+_WALK_LIST = frozenset({"allOf", "anyOf", "oneOf", "prefixItems"})
+
+
+def _subschemas(schema: object, path: str = "") -> Iterator[tuple[str, dict]]:
+    """Every subschema of `schema`, root first, in document order, with its path.
+
+    Structural, not blind: a PROPERTY named `$ref` is not a reference, and this walk never
+    mistakes it for one.
+    """
+    if not isinstance(schema, dict):
+        return
+    yield path, schema
+    for k, v in schema.items():
+        at = k if path == "" else f"{path}/{k}"
+        if k == "items" and isinstance(v, list):
+            for i, x in enumerate(v):
+                yield from _subschemas(x, f"{at}/{i}")
+        elif k in _WALK_SUBSCHEMA:
+            yield from _subschemas(v, at)
+        elif k in _WALK_MAP and isinstance(v, dict):
+            for n, x in v.items():
+                yield from _subschemas(x, f"{at}/{n}")
+        elif k in _WALK_LIST and isinstance(v, list):
+            for i, x in enumerate(v):
+                yield from _subschemas(x, f"{at}/{i}")
+
+
+def _draft3_sentence(uri: str) -> str:
+    return (
+        f"the schema's $schema {json.dumps(uri)} names draft 3, which this validator does not "
+        "support (draft-04, draft-06, draft-07, 2019-09 and 2020-12 are)"
+    )
+
+
+def _names_draft3(uri: object) -> bool:
+    if not isinstance(uri, str):
+        return False
+    found = jsonschema.validators.validator_for({"$schema": uri}, default=None)
+    return found is jsonschema.Draft3Validator
+
+
+# ---- `pattern`: the dialect both runtimes share, and its clock (#131, #132) ----------------
+
+# The opcodes `re` parses that the Node port cannot translate faithfully: look-behind
+# (fixed-width here, any width in JS), backreferences (a JS backreference to a group that did
+# not take part matches the empty string; here it fails), atomic groups, possessive
+# quantifiers and conditional groups. Inline flags and `\N{...}` are found below.
+_UNSUPPORTED_OPS = frozenset(
+    {_sre.ATOMIC_GROUP, _sre.POSSESSIVE_REPEAT, _sre.GROUPREF, _sre.GROUPREF_EXISTS}
+)
+
+
+def _names_a_character(pattern: str) -> bool:
+    """`\\N{...}` anywhere: it parses to a plain LITERAL, so the tree cannot show it."""
+    i = 0
+    while i < len(pattern):
+        if pattern[i] == "\\":
+            if pattern[i + 1 : i + 2] == "N":
+                return True
+            i += 2
+        else:
+            i += 1
+    return False
+
+
+def _tree_unsupported(items: object) -> bool:
+    for op, av in items:  # type: ignore[attr-defined]
+        if op in _UNSUPPORTED_OPS:
+            return True
+        if op in (_sre.ASSERT, _sre.ASSERT_NOT):
+            direction, sub = av
+            if direction < 0 or _tree_unsupported(sub):
+                return True
+        elif op is _sre.SUBPATTERN:
+            _group, add_flags, del_flags, sub = av
+            if add_flags or del_flags or _tree_unsupported(sub):
+                return True
+        elif op in (_sre.MAX_REPEAT, _sre.MIN_REPEAT):
+            if _tree_unsupported(av[2]):
+                return True
+        elif op is _sre.BRANCH:
+            if any(_tree_unsupported(sub) for sub in av[1]):
+                return True
+    return False
+
+
+def _pattern_unsupported(pattern: str) -> bool:
+    """True when `re` parses `pattern` and it uses a construct outside the shared dialect.
+
+    A pattern `re` refuses is NOT this function's: it is left to `check_schema`, which raises
+    where it always raised. `runtime-ts/src/pyjsonschema.ts` (`translatePyPattern`) parses
+    with `re._parser`'s own grammar and marks the same constructs, which is what makes the
+    refusal one sentence on both runtimes rather than two verdicts.
+    """
+    # `\\N{...}` first, whatever else the pattern holds: the port has no Unicode name table,
+    # so it cannot tell a defined name from an undefined one, and neither side tries to.
+    if _names_a_character(pattern):
+        return True
+    try:
+        parsed = _sre_parse.parse(pattern)
+    except (re.error, OverflowError, ValueError, RecursionError):
+        return False
+    # `(?u)` is the default for a str pattern; any other global flag is refused.
+    if parsed.state.flags & ~re.UNICODE:
+        return True
+    return _tree_unsupported(parsed.data)
+
+
+def _clip(text: str, limit: int = 200) -> str:
+    """At most `limit` codepoints of `text`, then `…(N more)` (#153)."""
+    if len(text) <= limit:
+        return text
+    return f"{text[:limit]}…({len(text) - limit} more)"
+
+
+def _unsupported_pattern_sentence(pattern: str) -> str:
+    return (
+        f"the pattern {_clip(repr(pattern))} is not supported: this validator refuses inline "
+        "flags, look-behind, backreferences, atomic groups, possessive quantifiers, "
+        "conditional groups and \\N{...} escapes"
+    )
+
+
+PATTERN_BUDGET_MS = 500
+
+
+def _pattern_budget_sentence(pattern: str) -> str:
+    return (
+        f"the pattern {_clip(repr(pattern))} did not finish within the {PATTERN_BUDGET_MS} ms "
+        "this validator allows a document's patterns; rewrite it so it cannot backtrack "
+        "catastrophically, as (a+)+$ does"
+    )
+
+
+class _PatternRefusal(Exception):
+    """Raised out of `jsonschema` mid-validation; `schema_error` answers its sentence."""
+
+
+# The search runs in a child interpreter because `re` holds the GIL for the whole of a
+# search: a catastrophic pattern in a worker thread still stops the event loop that answers
+# `ping` (measured: 0 ticks of the main thread during a 372 ms search). A child can be killed;
+# a running `re.search` cannot be interrupted from another thread on any platform.
+_CHILD_SOURCE = """
+import json, re, sys
+for line in sys.stdin.buffer:
+    pattern, text = json.loads(line)
+    try:
+        out = "1" if re.search(pattern, text) else "0"
+    except Exception as e:
+        out = json.dumps([type(e).__name__, str(e)])
+    sys.stdout.write(out + "\\n")
+    sys.stdout.flush()
+"""
+
+
+class _PatternChild:
+    """One long-lived `python -I -S` that answers `re.search`, restarted after a timeout."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._proc: subprocess.Popen[bytes] | None = None
+        self._lines: queue.Queue[bytes | None] = queue.Queue()
+
+    def _start(self) -> subprocess.Popen[bytes]:
+        proc = subprocess.Popen(
+            [sys.executable, "-I", "-S", "-c", _CHILD_SOURCE],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+        )
+        lines: queue.Queue[bytes | None] = queue.Queue()
+
+        def pump() -> None:
+            assert proc.stdout is not None
+            for line in proc.stdout:
+                lines.put(line)
+            lines.put(None)
+
+        threading.Thread(target=pump, daemon=True).start()
+        self._proc, self._lines = proc, lines
+        return proc
+
+    def _stop(self) -> None:
+        proc, self._proc = self._proc, None
+        if proc is not None:
+            proc.kill()
+            proc.wait()
+
+    def search(self, pattern: str, text: str, timeout: float) -> bool | None:
+        """The search's truth, or None when it ran past `timeout` seconds (the child is killed)."""
+        with self._lock:
+            proc = self._proc if self._proc is not None and self._proc.poll() is None else None
+            if proc is None:
+                self._stop()
+                proc = self._start()
+            assert proc.stdin is not None
+            proc.stdin.write(json.dumps([pattern, text]).encode("ascii") + b"\n")
+            proc.stdin.flush()
+            try:
+                line = self._lines.get(timeout=timeout)
+            except queue.Empty:
+                self._stop()
+                return None
+            if line is None:
+                self._stop()
+                raise RuntimeError("the pattern child exited without answering")
+            answer = line.decode("ascii").strip()
+            if answer in ("0", "1"):
+                return answer == "1"
+            kind, message = json.loads(answer)
+            raise (re.error if kind == "error" else getattr(builtins, kind, RuntimeError))(message)
+
+
+_PATTERN_CHILD = _PatternChild()
+_PATTERN_CLOCK: contextvars.ContextVar[list[float] | None] = contextvars.ContextVar(
+    "_PATTERN_CLOCK", default=None
+)
+
+
+class _BoundedRe:
+    """`jsonschema`'s `re`, with `search` charged to the running validation's clock.
+
+    Outside `schema_error` (no clock) it is `re` itself. Installed on the three `jsonschema`
+    modules that call `re.search` on a schema's pattern, so every keyword that searches —
+    `pattern`, `patternProperties`, `additionalProperties`, `unevaluatedProperties` — is
+    bounded without re-implementing any of them.
+    """
+
+    def __getattr__(self, name: str) -> object:
+        return getattr(re, name)
+
+    def search(self, pattern: object, string: object, flags: int = 0) -> object:
+        clock = _PATTERN_CLOCK.get()
+        if clock is None or flags or not isinstance(pattern, str) or not isinstance(string, str):
+            return re.search(pattern, string, flags)  # type: ignore[arg-type]
+        remaining = PATTERN_BUDGET_MS / 1000 - clock[0]
+        if remaining <= 0:
+            raise _PatternRefusal(_pattern_budget_sentence(pattern))
+        started = time.monotonic()
+        try:
+            found = _PATTERN_CHILD.search(pattern, string, remaining)
+        finally:
+            clock[0] += time.monotonic() - started
+        if found is None:
+            raise _PatternRefusal(_pattern_budget_sentence(pattern))
+        return found
+
+
+for _module in ("jsonschema._keywords", "jsonschema._utils", "jsonschema._legacy_keywords"):
+    importlib.import_module(_module).re = _BoundedRe()  # type: ignore[attr-defined]
+
+
+def _unsupported_schema(schema: dict) -> str | None:
+    """The one sentence BOTH runtimes answer for a schema the validator will not resolve.
+
+    `jsonschema` resolves a `$ref` against a base URI and a registry; the Node port resolves
+    it inside the one resource a caller schema is (`pyjsonschema.ts`, module header). So
+    that the two never disagree, the reference narrows itself to the same rule BEFORE
+    `jsonschema.validate` runs, eagerly and in document order: draft 3 anywhere, a reference
+    that is not fragment-only, an embedded `$id` (`id` under draft 4) beside any reference.
+    Each is answered as `{valid: false, feedback}` rather than raised — a model handed the
+    sentence can act on it (#125). A pointer to nowhere or an unknown anchor is found
+    lazily, from the `referencing` exceptions, in `schema_error`.
+    """
+    # `validator_for` on a non-string `$schema` raises (AttributeError) — both runtimes raise.
+    cls = jsonschema.validators.validator_for(schema)
+    if cls is jsonschema.Draft3Validator:
+        return _draft3_sentence(schema["$schema"])
+    id_key = "id" if cls is jsonschema.Draft4Validator else "$id"
+    refs: list[tuple[str, str]] = []
+    ids: list[str] = []
+    for path, sub in _subschemas(schema):
+        if path != "":
+            if _names_draft3(sub.get("$schema")):
+                return _draft3_sentence(sub["$schema"])
+            if isinstance(sub.get(id_key), str):
+                ids.append(path)
+        for k in _REF_KEYWORDS:
+            v = sub.get(k)
+            if isinstance(v, str):
+                refs.append((k, v))
+    for k, v in refs:
+        # `$recursiveRef`'s value is never read by the reference, so it is never judged.
+        if k != "$recursiveRef" and v != "" and not v.startswith("#"):
+            return (
+                f"the reference {json.dumps(v)} cannot be resolved: only references into this "
+                'schema ("#", "#/..." and "#name") are supported'
+            )
+    if refs and ids:
+        return (
+            f'the schema declares "{id_key}" at {ids[0]}; references are only resolved in a '
+            "schema with a single resource"
+        )
+    # #131: every `pattern` and `patternProperties` key, in document order.
+    for _path, sub in _subschemas(schema):
+        candidates = []
+        if isinstance(sub.get("pattern"), str):
+            candidates.append(sub["pattern"])
+        if isinstance(sub.get("patternProperties"), dict):
+            candidates.extend(sub["patternProperties"])
+        for candidate in candidates:
+            if isinstance(candidate, str) and _pattern_unsupported(candidate):
+                return _unsupported_pattern_sentence(candidate)
+    return None
+
+
 def schema_error(output: str, schema: dict) -> str | None:
-    """Return a pointed validation error for `output`, or None if it satisfies `schema`."""
+    """Return a pointed validation error for `output`, or None if it satisfies `schema`.
+
+    A schema the validator will not resolve (see `_unsupported_schema`) returns its one
+    sentence here too, so `validate_json` answers it instead of raising.
+    """
     try:
-        data = extract_json(output)
-    except ValueError as e:
-        return parse_error_message(e)
+        # #152: a whole-text JSON document of any type first — `"x"`, `1.0` and `null` are
+        # JSON texts — and only then the object/array search `extract_json` does.
+        data = json.loads(_unfenced(output))
+    except ValueError:
+        try:
+            data = extract_json(output)
+        except ValueError as e:
+            return parse_error_message(e)
+    if isinstance(schema, dict):
+        refusal = _unsupported_schema(schema)
+        if refusal is not None:
+            return refusal
+    token = _PATTERN_CLOCK.set([0.0])
     try:
         jsonschema.validate(data, schema)
+    except _PatternRefusal as e:
+        return str(e)
     except jsonschema.ValidationError as e:
         where = "/".join(str(p) for p in e.absolute_path) or "root"
-        return validation_error_message(where, e.message)
+        return validation_error_message(_clip(where), _clip_detail(e.message, e.instance))
+    except _WrappedReferencingError as e:
+        wrapped = e._wrapped
+        if isinstance(wrapped, PointerToNowhere):
+            ref = json.dumps("#" + wrapped.ref)
+            return f"the reference {ref} points at nothing in this schema"
+        if isinstance(wrapped, NoSuchAnchor):
+            anchor = json.dumps("#" + wrapped.anchor)
+            return f"the reference {anchor} names no anchor in this schema"
+        raise
+    finally:
+        _PATTERN_CLOCK.reset(token)
     return None
 
 
+def _clip_detail(message: str, instance: object) -> str:
+    """#153: the offending value quoted at most 200 codepoints, the sentence at most 1000.
+
+    Every `repr` of the instance in the message is clipped first, so a `maxLength` failure on a
+    1 MiB string still says `is too long`; the whole sentence is then capped, which bounds the
+    values a message quotes that are PARTS of the instance (an unexpected property's name).
+    """
+    quoted = repr(instance)
+    if len(quoted) > 200:
+        message = message.replace(quoted, _clip(quoted))
+    return _clip(message, 1000)
+
+
 def render_evidence(messages: list[Message], budget: int = 4096) -> str:
     """Tool call/observation pairs from a run's transcript, as critic-readable lines."""
     contract = load_contract()

{bantamkit-0.35.6 → bantamkit-0.35.8}/src/bantamkit/eventlog.py

@@ -196,10 +196,23 @@ class EventLog:
         path: Path | None,
         cap_bytes: int = CAP_BYTES,
         clock: Callable[[], int] = _default_clock,
+        requires_dir: Path | None = None,
     ) -> None:
         self.path = path
         self.cap_bytes = cap_bytes
         self._clock = clock
+        #: job65/#154: the directory that must already exist before a record is written.
+        #:
+        #: `from_env` sets it to the store root when the switch is `on` (the default file
+        #: lives INSIDE the store). WAS: the `mkdir` in `_append` brought a never-saved store
+        #: into existence -- `--store <absent>` plus one `work_plan` call left
+        #: `<store>/events/mcp.jsonl` behind, and the next layered session walking up through
+        #: it bound that directory as its store. The log does not create the store: while the
+        #: store is not there a record has nowhere to go and is DROPPED -- not redirected, and
+        #: not counted as `write_failed`, because nothing was offered to the filesystem. The
+        #: first save creates the store; records after it land. A literal path is the
+        #: operator's own choice and keeps `requires_dir` None.
+        self.requires_dir = requires_dir
         #: Set the first time `record` swallows an `OSError`, and never cleared.
         #:
         #: FAILING TO LOG STILL NEVER FAILS THE TOOL — that contract is unchanged and
@@ -225,7 +238,13 @@ class EventLog:
         clock: Callable[[], int] = _default_clock,
     ) -> EventLog:
         source = os.environ if env is None else env
-        return cls(resolve_path(store_root, source.get(EVENT_LOG_ENV)), clock=clock)
+        raw = source.get(EVENT_LOG_ENV)
+        in_store = raw is not None and raw.strip().lower() in _ON
+        return cls(
+            resolve_path(store_root, raw),
+            clock=clock,
+            requires_dir=Path(store_root) if in_store else None,
+        )
 
     @property
     def enabled(self) -> bool:
@@ -280,6 +299,10 @@ class EventLog:
         intent, not a live path.
         """
         assert self.path is not None
+        # job65/#154: `is_dir()` raises PermissionError for EACCES, which lands in `record`'s
+        # `except OSError` as a lost record -- the verdict `eventlog.ts` reaches too.
+        if self.requires_dir is not None and not self.requires_dir.is_dir():
+            return
         # AUDIT FINDING (J51-1): this `mkdir(parents=True)` can bring a whole `.bantamkit`
         # directory into existence on its own -- `BANTAMKIT_EVENT_LOG=on` with a project
         # store that was never saved to reaches here first -- entirely bypassing