bantamkit 0.34.3__tar.gz → 0.35.0__tar.gz

{bantamkit-0.34.3 → bantamkit-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bantamkit
-Version: 0.34.3
+Version: 0.35.0
 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
@@ -55,7 +55,7 @@ easy.
 | [Configuration](#configuration) | Every flag and variable, with its default |
 | [Update](#update) | `--update`, pipx, uv, then restart |
 | [Troubleshooting](#troubleshooting) | Timeouts, refusals, the wrong store |
-| [What it serves](#what-it-serves) | 12 tools, one prompt, two resource templates |
+| [What it serves](#what-it-serves) | 14 tools, one prompt, two resource templates |
 | [Requirements](#requirements) | Python and dependencies |
 | [The asset pack](#the-asset-pack) | `--assets-root`, `BANTAMKIT_ASSETS` |
 | [The operator CLI: `python -m bantamkit.memory`](#the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore |
@@ -88,7 +88,8 @@ python -m venv <env>
 ```
 
 `--install` records the venv's console script by absolute path with `"args": []`, so no launch
-needs the network or your shell's PATH. Measured on macOS arm64, it served 12 tools under a GUI
+needs the network or your shell's PATH. Measured on macOS arm64 (served-tools: dated — the
+surface was twelve then), it served 12 tools under a GUI
 app's PATH, `/usr/bin:/bin:/usr/sbin:/sbin`; the Windows layout (`<env>\Scripts\`) was not.
 
 **No network on the target? Carry a wheelhouse.** Download it on a machine with the **same OS,
@@ -96,9 +97,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.34.3" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.0" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.34.3"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.0"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -272,7 +273,7 @@ you**; a new version with an old `build_id` means an old process.
 
 ## What it serves
 
-12 tools, the `bantamkit_status` prompt and two resource templates
+It serves 14 tools, the `bantamkit_status` prompt and two resource templates
 (`bantamkit://skills/{name}`, `bantamkit://rubrics/{name}`):
 
 | Tool | What it does |
@@ -286,6 +287,8 @@ you**; a new version with an old `build_id` means an old process.
 | `shiftwork_clock_in` | open a unit of work and get its brief |
 | `shiftwork_clock_out` | close a unit with status and accounting |
 | `shiftwork_status` | report the open cursor |
+| `shiftwork_plan` | read-only: which units of a checkpoint its `depends_on` graph permits to run at once. Never moves the cursor |
+| `work_plan` | turn any `{id, depends_on, priority}` graph into the batches that may run in parallel, plus the widest fan-out |
 | `token_ledger` | what a session cost, read off the host's transcripts |
 | `bantamkit_status` | report store health against its budget |
 | `build_identity` | report the fingerprint of the source on disk, not the executing code — useful when a machine carries two installs under one name |

{bantamkit-0.34.3 → bantamkit-0.35.0}/README.md

@@ -27,7 +27,7 @@ easy.
 | [Configuration](#configuration) | Every flag and variable, with its default |
 | [Update](#update) | `--update`, pipx, uv, then restart |
 | [Troubleshooting](#troubleshooting) | Timeouts, refusals, the wrong store |
-| [What it serves](#what-it-serves) | 12 tools, one prompt, two resource templates |
+| [What it serves](#what-it-serves) | 14 tools, one prompt, two resource templates |
 | [Requirements](#requirements) | Python and dependencies |
 | [The asset pack](#the-asset-pack) | `--assets-root`, `BANTAMKIT_ASSETS` |
 | [The operator CLI: `python -m bantamkit.memory`](#the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore |
@@ -60,7 +60,8 @@ python -m venv <env>
 ```
 
 `--install` records the venv's console script by absolute path with `"args": []`, so no launch
-needs the network or your shell's PATH. Measured on macOS arm64, it served 12 tools under a GUI
+needs the network or your shell's PATH. Measured on macOS arm64 (served-tools: dated — the
+surface was twelve then), it served 12 tools under a GUI
 app's PATH, `/usr/bin:/bin:/usr/sbin:/sbin`; the Windows layout (`<env>\Scripts\`) was not.
 
 **No network on the target? Carry a wheelhouse.** Download it on a machine with the **same OS,
@@ -68,9 +69,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.34.3" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.0" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.34.3"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.0"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -244,7 +245,7 @@ you**; a new version with an old `build_id` means an old process.
 
 ## What it serves
 
-12 tools, the `bantamkit_status` prompt and two resource templates
+It serves 14 tools, the `bantamkit_status` prompt and two resource templates
 (`bantamkit://skills/{name}`, `bantamkit://rubrics/{name}`):
 
 | Tool | What it does |
@@ -258,6 +259,8 @@ you**; a new version with an old `build_id` means an old process.
 | `shiftwork_clock_in` | open a unit of work and get its brief |
 | `shiftwork_clock_out` | close a unit with status and accounting |
 | `shiftwork_status` | report the open cursor |
+| `shiftwork_plan` | read-only: which units of a checkpoint its `depends_on` graph permits to run at once. Never moves the cursor |
+| `work_plan` | turn any `{id, depends_on, priority}` graph into the batches that may run in parallel, plus the widest fan-out |
 | `token_ledger` | what a session cost, read off the host's transcripts |
 | `bantamkit_status` | report store health against its budget |
 | `build_identity` | report the fingerprint of the source on disk, not the executing code — useful when a machine carries two installs under one name |

bantamkit-0.35.0/_assets/tools/shiftwork_plan.json

@@ -0,0 +1,25 @@
+{
+  "name": "shiftwork_plan",
+  "description": "Shift-work plan: read-only batch view of a checkpoint — which units its `depends_on` graph permits to run in parallel. Answers `{\"result\": \"plan\", \"batches\", \"ready\", \"sequence\", \"width\", \"cursor\"}`: `ready` is `batches[0]`, the units dispatchable right now, and `width` is the largest batch length, the widest fan-out. Units with status `done` or `dropped` are satisfied — dropped from the graph, and edges pointing at them treated as already resolved; `todo`, `in_progress` and `blocked` stay in it. Every unit has priority 0, because the checkpoint schema has no priority field, so order inside a batch is `plan.units` order. Same refusal sentences as `work_plan` for a duplicate id, an unknown dependency or a cycle, and the same refusals `shiftwork_status` gives for a checkpoint it cannot read. It reports what the dependency graph permits; it does not move the cursor, which is echoed unchanged so the single-pointer contract and the batch view can be read side by side. An orchestrator stays responsible for what it actually dispatches: `depends_on` encodes logical order, not file contention. Never mutates.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      }
+    },
+    "required": [
+      "checkpoint"
+    ],
+    "type": "object",
+    "title": "shiftwork_planArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "shiftwork_planDictOutput"
+  }
+}

bantamkit-0.35.0/_assets/tools/work_plan.json

@@ -0,0 +1,49 @@
+{
+  "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}` — `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. Three refusals, checked in this order and one sentence each: `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": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Ids this node waits for; every one of them must be declared by some node"
+            },
+            "priority": {
+              "type": "integer",
+              "description": "Tie-break inside a batch, descending. Optional; 0 when absent"
+            }
+          },
+          "required": [
+            "id",
+            "depends_on"
+          ]
+        }
+      }
+    },
+    "required": [
+      "nodes"
+    ],
+    "type": "object",
+    "title": "work_planArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "work_planDictOutput"
+  }
+}

{bantamkit-0.34.3 → bantamkit-0.35.0}/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.34.3"
+__version__ = "0.35.0"

{bantamkit-0.34.3 → bantamkit-0.35.0}/src/bantamkit/eventlog.py

@@ -30,11 +30,13 @@ THREE HARD RULES, each with the failure it prevents:
   byte-compares both runtimes' streams; one stray write breaks the wire suite. Nothing
   in this module touches `sys.stderr` or `sys.stdout`.
 * **Metadata only.** Never a tool argument's value, never a memory body, never a
-  validated output, never a query, never a document row. Eight of the twelve tools take
+  validated output, never a query, never a document row. Nine of the fourteen tools take
   an unbounded string (counted over `assets/tools/`: a `string` parameter with no `enum`
   or `maxLength`, or an array of such; `bantamkit_read` and `repo_map` were two more until
-  job50 I5 retired them from the roster) and among those `skill_audit`'s `root`,
-  `token_ledger`'s `root` and `prices` and the three shift-work tools' `checkpoint` are
+  job50 I5 retired them from the roster — and `work_plan` is NOT one of them: its `nodes`
+  is an array of objects, not an array of strings, so the rule does not reach the ids
+  inside it) and among those `skill_audit`'s `root`,
+  `token_ledger`'s `root` and `prices` and the four shift-work tools' `checkpoint` are
   absolute paths; each record carries counts and tokens from a closed set, never the
   path, never a part name, never a skill id, never a mapped file, never a session id,
   never a model name. The dormant `bantamkit_read` and `repo_map` handlers keep the same

{bantamkit-0.34.3 → bantamkit-0.35.0}/src/bantamkit/mcpserver.py

@@ -30,6 +30,7 @@ from bantamkit import (
     shiftwork,
     skillaudit,
     tokenledger,
+    workplan,
 )
 from bantamkit.assets import AssetNotFound, assets_root, load_skill, load_tool_asset
 from bantamkit.client import BantamError
@@ -1474,6 +1475,24 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
             _record_result(log, "shiftwork_status", lambda: shiftwork.status(checkpoint))
         )
 
+    def work_plan(nodes: list[dict[str, Any]]) -> dict[str, Any]:
+        # `result` is added HERE and not in `workplan.plan`, which is Layer 1 and answers
+        # the computation (`batches`, `sequence`, `width`) rather than a wire shape. The
+        # wire shape is the tool asset's, so the verdict key is put on at the seam that
+        # serves it — the same division `plan_batches` uses one layer down. A refusal
+        # already carries its own `result` and passes through untouched, because
+        # `_record_result` reads that key to write the register's verdict to the log.
+        def answered() -> dict[str, Any]:
+            plan = workplan.plan(nodes)
+            return plan if plan.get("result") == "error" else {"result": "plan", **plan}
+
+        return _noted_dict(_record_result(log, "work_plan", answered))
+
+    def shiftwork_plan(checkpoint: str) -> dict[str, Any]:
+        return _noted_dict(
+            _record_result(log, "shiftwork_plan", lambda: shiftwork.plan_batches(checkpoint))
+        )
+
     # A TOOL and not a resource or an `initialize` field, because the gap RB-P84 names is
     # an AGENT MID-CALL: the host reads `serverInfo` once at handshake and the
     # tool-calling model never sees it, and `resources/read` is a host-facing surface
@@ -1832,6 +1851,8 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
         _from_manifest(skill_audit, "skill_audit"),
         _from_manifest(memory_dream, "memory_dream"),
         _from_manifest(token_ledger, "token_ledger"),
+        _from_manifest(work_plan, "work_plan"),
+        _from_manifest(shiftwork_plan, "shiftwork_plan"),
     ]
 
     server = MCPServer(

{bantamkit-0.34.3 → bantamkit-0.35.0}/src/bantamkit/memory/__main__.py

@@ -2,7 +2,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 twelve-tool surface holds to it; `compact` is the one
+model decision" — 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). That position is only coherent if the operator can actually make the
 decision. Measured

{bantamkit-0.34.3 → bantamkit-0.35.0}/src/bantamkit/shiftwork.py

@@ -67,7 +67,9 @@ a missing one.
 
 Cursor advance is v1-linear: it moves to the first non-terminal unit in plan
 order and ignores `depends_on` — non-linear plans need a planner unit to
-reorder `plan.units` first.
+reorder `plan.units` first. `plan_batches` below READS `depends_on` and answers
+the batch view, so the module no longer ignores the field; what still ignores it
+is CURSOR ADVANCE, and the batch view is read-only and moves nothing.
 
 No lock: the MCP topology has one orchestrator by construction. The driver's
 O_EXCL lock guards cross-process races this shape does not have, and clock-out
@@ -84,6 +86,7 @@ from typing import Any
 
 import jsonschema
 
+from bantamkit import workplan
 from bantamkit.assets import AssetNotFound, load_schema, load_tool_asset
 from bantamkit.contract import schema_error
 
@@ -550,3 +553,67 @@ def status(checkpoint: str) -> dict[str, Any]:
         "open_questions": len(document["handoff"]["open_questions"]),
         "last_history": history[-1] if history else None,
     }
+
+
+def plan_batches(checkpoint: str) -> dict[str, Any]:
+    """Read-only batch view of a checkpoint. Never mutates.
+
+    The adapter over `workplan.plan`, and it holds no graph logic of its own: a loop over
+    `depends_on` here would be Layer 1's work done in Layer 5. Its whole content is the
+    three decisions below plus the shape it answers in.
+
+    **A `done` or `dropped` unit is SATISFIED**, which is two things and not one: it
+    leaves the graph, AND every edge pointing at it is treated as already resolved. Only
+    the first would be a defect rather than a simplification — `workplan.plan` refuses an
+    edge into an id no node declares, so dropping the unit while keeping the edge would
+    make every checkpoint with one finished unit unplannable, which is every checkpoint
+    after its first clock-out. `todo`, `in_progress` and `blocked` are all still work and
+    all stay in. The terminal pair is `TERMINAL_UNIT_STATUS`, the same constant the
+    driver's success test uses, so "finished" means one thing in this module.
+
+    **Every unit gets priority 0.** The checkpoint schema has no priority field and this
+    design does not add one, so the tie-break inside a batch falls through to the core's
+    insertion order — `plan.units` order, which is the order a reader of the checkpoint
+    already sees.
+
+    **The cursor is ECHOED, never written.** `clock_out` remains the only thing that
+    moves it and stays v1-linear; this tool reports what the graph PERMITS beside the
+    single pointer that says what the driver will actually do next, so an orchestrator
+    can read the two side by side and decide. Advisory, in one direction only.
+
+    Returns `{"result": "plan", "batches", "ready", "sequence", "width", "cursor"}` —
+    `ready` is `batches[0]`, or `[]` when the plan is all terminal, which is an ANSWER
+    and not a refusal. Refusals pass through verbatim in both directions: `_read_valid`'s
+    for a checkpoint that cannot be read or does not validate, and the core's own
+    duplicate-id / unknown-dependency / cycle sentences for a graph that cannot batch.
+    """
+    document, refusal = _read_valid(Path(checkpoint))
+    if refusal is not None:
+        return refusal
+    nodes = [
+        # `depends_on` is required by the schema, so `_read_valid` has already refused a
+        # unit without it and the default below cannot fire here. It is written anyway
+        # because the Node adapter reaches the same mapping and MUST default it too: a
+        # default on one side only is how two runtimes come to disagree about real data.
+        {"id": unit["id"], "depends_on": list(unit.get("depends_on") or []), "priority": 0}
+        for unit in document["plan"]["units"]
+        if unit["status"] not in TERMINAL_UNIT_STATUS
+    ]
+    satisfied = {
+        unit["id"] for unit in document["plan"]["units"] if unit["status"] in TERMINAL_UNIT_STATUS
+    }
+    for node in nodes:
+        node["depends_on"] = [dep for dep in node["depends_on"] if dep not in satisfied]
+
+    answer = workplan.plan(nodes)
+    if answer.get("result") == "error":
+        return answer
+    batches = answer["batches"]
+    return {
+        "result": "plan",
+        "batches": batches,
+        "ready": batches[0] if batches else [],
+        "sequence": answer["sequence"],
+        "width": answer["width"],
+        "cursor": document["plan"]["cursor"],
+    }

bantamkit-0.35.0/src/bantamkit/workplan.py

@@ -0,0 +1,157 @@
+"""Layer 1 — a deterministic work-plan planner: turn `depends_on` into batches.
+
+`assets/schemas/shiftwork-checkpoint.json` has carried `plan.units[].depends_on` since
+the contract was written and neither runtime has ever read it: cursor advance is
+v1-linear in both, so every job this repo ran was executed as a straight line whatever
+its dependency graph said. Measured 2026-09-18 over the 19 checkpoints in `.shiftwork/`,
+215 units collapse to 119 batches — 96 serial steps (44.7 %) were false serialization.
+
+This module is the mechanism underneath that. It is **Layer 1 (Core)** per
+docs/architecture.md: a pure function, no filesystem, no clock, no `mcp` import, no
+dependency outside the standard library. The shift-work adapter (Layer 5) and the tool
+assets (Layer 2) are separate units in separate files, because a change lives in exactly
+one layer.
+
+The semantics are the documented defaults of `ex-flow@1.1.0` — the user's own MIT
+package, which is what made the measurement above possible. It is the SPECIFICATION and
+deliberately NOT a dependency: `runtime-ts/package.json` declares exactly one runtime
+dependency, and `docs/porting.md` uses "no runtime dependency is allowed into
+`runtime-ts`" as the live justification for three divergence rows. Taking `ex-flow`
+would collapse that argument to save a hundred lines of graph code, and `runtime_py`
+could not import it in any case. So both runtimes hand-write it and the conformance
+suite proves they agreed. Design:
+`docs/superpowers/specs/2026-09-18-workplan-dag-design.md`.
+
+Determinism is not a nicety here — it is the whole gate. Two implementations that both
+"topologically sort correctly" can still disagree about the order inside a batch and
+about WHICH cycle they name in a graph that has two, and either disagreement turns the
+conformance suite red for a reason that is not a defect. Hence the two ordering rules
+below are stated as contract, not as an artifact of whatever the dict happened to do.
+"""
+
+from typing import Any
+
+__all__ = ["plan"]
+
+
+def _cycle_path(order: list[str], deps: dict[str, list[str]], pending: set[str]) -> list[str]:
+    """Name one cycle among the nodes Kahn could not emit, reproducibly in any language.
+
+    A graph can hold several cycles and every one of them is an equally correct answer,
+    so "find a cycle" is not a specification — two runtimes would name two different
+    ones and the differential would go red over nothing. The rule is therefore fixed:
+    scan the un-emitted nodes in INPUT order, walk `depends_on` in DECLARED order, and
+    the first repeated id closes the cycle. First node scanned, first edge walked, first
+    repeat wins.
+
+    Only un-emitted dependencies are walked. An id Kahn already emitted sits in a batch
+    below and can never be part of a cycle, so following one would be a dead end rather
+    than a different answer.
+
+    The walk may begin at a node that is merely downstream of a cycle rather than in one
+    (`a -> b -> c -> b`: `a` cannot be emitted, but `a` is not in the cycle). What is
+    returned is the CYCLE, `b -> c -> b`, trimmed at the first occurrence of the repeated
+    id — the tail that only led into it is not part of it.
+    """
+    start = next(node_id for node_id in order if node_id in pending)
+    path = [start]
+    seen = {start: 0}
+    current = start
+    while True:
+        nxt = next((dep for dep in deps[current] if dep in pending), None)
+        if nxt is None:
+            # Unreachable for a graph Kahn stalled on: a node is only left pending
+            # because at least one dependency of it is also still pending.
+            return path + [path[0]]
+        if nxt in seen:
+            return path[seen[nxt]:] + [nxt]
+        seen[nxt] = len(path)
+        path.append(nxt)
+        current = nxt
+
+
+def plan(nodes: list[dict[str, Any]]) -> dict[str, Any]:
+    """Batch a dependency graph into the levels that may run in parallel.
+
+    nodes: [{"id": str, "depends_on": list[str], "priority": int}] — `depends_on`
+    defaults to empty and `priority` defaults to 0, because the shift-work checkpoint
+    schema has no priority field and this design does not add one.
+
+    Returns either
+
+        {"batches": [[id, ...], ...], "sequence": [id, ...], "width": int}
+
+    where batch *k* holds every node whose dependencies all appear in batches < *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) — or a structured refusal
+
+        {"result": "error", "reason": str}
+
+    which is the shape `shiftwork.py` already returns, so nothing new is invented for it.
+
+    **Ordering inside a batch is priority descending, then insertion order** — the order
+    the nodes were given, which for the shift-work adapter is `plan.units` order. Both
+    halves are contract: the second is what makes two independent implementations agree.
+
+    `plan([])` is `{"batches": [], "sequence": [], "width": 0}`. An empty plan is an
+    ANSWER, not a refusal — the same reasoning `shiftwork.clock_in` already applies when
+    its all-terminal test reports success instead of escalating on a dangling cursor.
+
+    The three refusals are checked in a fixed order — duplicate id, then unknown
+    dependency, then cycle — so a graph carrying two faults always names the same one.
+    The later checks would be meaningless on the earlier faults' input anyway: a
+    duplicate id makes "which node declares this" ambiguous, and an edge into a node
+    that does not exist is not a cycle.
+    """
+    order: list[str] = []
+    deps: dict[str, list[str]] = {}
+    priority: dict[str, int] = {}
+
+    for node in nodes:
+        node_id = node["id"]
+        if node_id in deps:
+            return {"result": "error", "reason": f"duplicate node id {node_id}"}
+        order.append(node_id)
+        deps[node_id] = list(node.get("depends_on") or [])
+        priority[node_id] = node.get("priority", 0)
+
+    for node_id in order:
+        for dep in deps[node_id]:
+            if dep not in deps:
+                return {
+                    "result": "error",
+                    "reason": f"node {node_id} depends on {dep}, which no node declares",
+                }
+
+    # Insertion index is the tie-break, so it is carried explicitly rather than being
+    # left to the incidental order of a set or dict during the sweep below.
+    index = {node_id: i for i, node_id in enumerate(order)}
+
+    pending = set(order)
+    emitted: set[str] = set()
+    batches: list[list[str]] = []
+
+    while pending:
+        ready = [
+            node_id
+            for node_id in order
+            if node_id in pending and all(dep in emitted for dep in deps[node_id])
+        ]
+        if not ready:
+            path = _cycle_path(order, deps, pending)
+            return {
+                "result": "error",
+                "reason": "the graph has a cycle: " + " -> ".join(path),
+            }
+        ready.sort(key=lambda node_id: (-priority[node_id], index[node_id]))
+        batches.append(ready)
+        pending.difference_update(ready)
+        emitted.update(ready)
+
+    sequence = [node_id for batch in batches for node_id in batch]
+    return {
+        "batches": batches,
+        "sequence": sequence,
+        "width": max((len(batch) for batch in batches), default=0),
+    }

{bantamkit-0.34.3 → bantamkit-0.35.0}/tests/data/served-tool-surface.json

@@ -11,7 +11,9 @@
     "memory_compact",
     "skill_audit",
     "memory_dream",
-    "token_ledger"
+    "token_ledger",
+    "work_plan",
+    "shiftwork_plan"
   ],
   "tools": {
     "bantamkit_status": {
@@ -449,6 +451,72 @@
         "type": "object",
         "title": "token_ledgerOutput"
       }
+    },
+    "work_plan": {
+      "description": "Work plan: turn a dependency graph into the batches that may run in parallel. Takes `nodes`, each `{id, depends_on, priority}` — `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. Three refusals, checked in this order and one sentence each: `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.",
+      "inputSchema": {
+        "properties": {
+          "nodes": {
+            "title": "Nodes",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "The node's identifier, unique across `nodes`"
+                },
+                "depends_on": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Ids this node waits for; every one of them must be declared by some node"
+                },
+                "priority": {
+                  "type": "integer",
+                  "description": "Tie-break inside a batch, descending. Optional; 0 when absent"
+                }
+              },
+              "required": [
+                "id",
+                "depends_on"
+              ]
+            }
+          }
+        },
+        "required": [
+          "nodes"
+        ],
+        "type": "object",
+        "title": "work_planArguments"
+      },
+      "outputSchema": {
+        "type": "object",
+        "additionalProperties": true,
+        "title": "work_planDictOutput"
+      }
+    },
+    "shiftwork_plan": {
+      "description": "Shift-work plan: read-only batch view of a checkpoint — which units its `depends_on` graph permits to run in parallel. Answers `{\"result\": \"plan\", \"batches\", \"ready\", \"sequence\", \"width\", \"cursor\"}`: `ready` is `batches[0]`, the units dispatchable right now, and `width` is the largest batch length, the widest fan-out. Units with status `done` or `dropped` are satisfied — dropped from the graph, and edges pointing at them treated as already resolved; `todo`, `in_progress` and `blocked` stay in it. Every unit has priority 0, because the checkpoint schema has no priority field, so order inside a batch is `plan.units` order. Same refusal sentences as `work_plan` for a duplicate id, an unknown dependency or a cycle, and the same refusals `shiftwork_status` gives for a checkpoint it cannot read. It reports what the dependency graph permits; it does not move the cursor, which is echoed unchanged so the single-pointer contract and the batch view can be read side by side. An orchestrator stays responsible for what it actually dispatches: `depends_on` encodes logical order, not file contention. Never mutates.",
+      "inputSchema": {
+        "properties": {
+          "checkpoint": {
+            "title": "Checkpoint",
+            "type": "string"
+          }
+        },
+        "required": [
+          "checkpoint"
+        ],
+        "type": "object",
+        "title": "shiftwork_planArguments"
+      },
+      "outputSchema": {
+        "type": "object",
+        "additionalProperties": true,
+        "title": "shiftwork_planDictOutput"
+      }
     }
   }
 }

{bantamkit-0.34.3 → bantamkit-0.35.0}/tests/test_eventlog.py

@@ -332,7 +332,7 @@ async def test_a_raising_handler_names_the_type_and_leaks_no_argument_value(tmp_
 
 @synchronous
 async def test_no_free_text_argument_reaches_the_file(tmp_path):
-    """Eight of the twelve tools take an unbounded string. None of it is on disk.
+    """Nine of the fourteen tools take an unbounded string. None of it is on disk.
 
     (The count is `eventlog.py`'s rule over `assets/tools/`: a `string` parameter with no
     `enum` or `maxLength`, or an array of such.) `skill_audit`'s `root` is covered by

{bantamkit-0.34.3 → bantamkit-0.35.0}/tests/test_layers.py

@@ -216,6 +216,10 @@ CORE_MODULES = (
     "critique.py",
     "evalrun.py",
     "mcpserver.py",
+    # 2026-09-18, W3. `workplan.py` landed as a Layer 1 core module in W1 and its purity
+    # was asserted by its own docstring and nothing mechanical. MEASURED before adding it:
+    # a contract literal pasted into it left this file at `44 passed`.
+    "workplan.py",
 )
 LAYER_MODULES = ("contract.py", "profile.py")
 FORBIDDEN_IMPORTS = (