bantamkit-mcp 0.35.0 → 0.35.2

package/dist/eventlog.js

@@ -32,11 +32,14 @@
  *   one stray write breaks the wire suite. Nothing in this module names `process.stdout`,
  *   `process.stderr` or `console`.
  * * **Metadata only.** Never a tool argument's value, never a memory body, never a
- *   validated output, never a query, never a document row. Most of the twelve tools take
- *   unbounded free text and two take absolute paths (`skill_audit`'s `root`, and
- *   `token_ledger`'s `root` and `prices`; `bantamkit_read`'s `path` and `repo_map`'s `root`
- *   and `focus` were two more until both tools left the roster — job50 I5, 2026-09-12 — and
- *   their DORMANT handlers still record the same way); each record carries counts and
+ *   validated output, never a query, never a document row. Nine of the fourteen tools take
+ *   an unbounded string and among those `skill_audit`'s `root`, `token_ledger`'s `root` and
+ *   `prices` and the four shift-work tools' `checkpoint` are absolute paths
+ *   (`bantamkit_read`'s `path` and `repo_map`'s `root` and `focus` were two more until both
+ *   tools left the roster — job50 I5, 2026-09-12 — and their DORMANT handlers still record
+ *   the same way; `work_plan` is NOT one of the nine: its `nodes` is an array of objects,
+ *   not an array of strings, so the rule does not reach the ids inside it); 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).
  *   Every value written here is an ASCII token from a closed set, a number, or a boolean.

package/dist/mcp/pyargs.d.ts

@@ -31,7 +31,7 @@ import { type PyValue } from '../pyjson.js';
 /** What a parameter accepts. `optional` is `| None = None` in the signature. */
 export interface FieldSpec {
     readonly name: string;
-    readonly kind: 'str' | 'int' | 'bool' | 'dict' | 'dictInt' | 'dictStr' | 'listStr';
+    readonly kind: 'str' | 'int' | 'bool' | 'dict' | 'dictInt' | 'dictStr' | 'listDict' | 'listStr';
     readonly optional: boolean;
     /** `Field(le=...)`: an inclusive ceiling, checked AFTER the lax int parse succeeds. */
     readonly le?: bigint;

package/dist/mcp/pyargs.js

@@ -174,6 +174,16 @@ export const ARG_MODELS = {
             opt('versions', 'dictStr'),
         ],
     },
+    // `work_plan(nodes: list[dict[str, Any]])` on the reference (W4). The only
+    // `list[dict[...]]` on the surface and the reason `listDict` exists: pydantic validates
+    // the list's ITEMS, one error per bad element and in the list's own order, with the
+    // INDEX in the location — `nodes.0`, the way `listStr` reports it. `dict[str, Any]` puts
+    // no constraint on what is INSIDE a node, so `{}` and `{'id': 5}` both validate here and
+    // reach `workplan.plan`, exactly as they do on the reference.
+    work_plan: { model: 'work_planArguments', fields: [req('nodes', 'listDict')] },
+    // `shiftwork_plan(checkpoint: str)` — the same one strict `str` the other four
+    // shift-work tools take.
+    shiftwork_plan: { model: 'shiftwork_planArguments', fields: [req('checkpoint', 'str')] },
 };
 /** `type(value).__name__`, for the `input_type=` half of the sentence. */
 function pyTypeName(value) {
@@ -287,6 +297,28 @@ function checkField(spec, value) {
             }
             return bad.length > 0 ? bad : { value: { t: 'dict', v: coerced } };
         }
+        case 'listDict': {
+            // `list[dict[str, Any]]`. The same shape as `listStr` below with the `dict`
+            // validator on the items: measured against pydantic 2.13, `{'nodes': 'x'}` is one
+            // `list_type` at `nodes` and `{'nodes': [1, {...}, 'z']}` is TWO `dict_type` errors,
+            // `nodes.0` and `nodes.2` — every bad item, not the first.
+            if (value.t !== 'list') {
+                return [{ loc: spec.name, type: 'list_type', msg: 'Input should be a valid list', input: value }];
+            }
+            const bad = [];
+            for (let i = 0; i < value.v.length; i += 1) {
+                const item = value.v[i];
+                if (item.t !== 'dict') {
+                    bad.push({
+                        loc: `${spec.name}.${i}`,
+                        type: 'dict_type',
+                        msg: 'Input should be a valid dictionary',
+                        input: item,
+                    });
+                }
+            }
+            return bad.length > 0 ? bad : { value };
+        }
         case 'listStr': {
             if (value.t !== 'list') {
                 return [{ loc: spec.name, type: 'list_type', msg: 'Input should be a valid list', input: value }];

package/dist/mcp/server.d.ts

@@ -4,13 +4,20 @@ import { EventLog } from '../eventlog.js';
 import type { Memory } from '../memory/component.js';
 import type { RawStdioTransport } from './transport.js';
 /**
- * The twelve, in the order `build_server` lists them — which is the order `tools/list` emits.
+ * The fourteen, in the order `build_server` lists them — which is the order `tools/list` emits.
  *
  * `bantamkit_status` went LAST rather than first, `memory_compact` after it rather than
  * beside `memory_save` where a reader would look for it, `skill_audit` after that,
- * `memory_dream` after that and `token_ledger` after that, for the same reason the reference
- * appends: registration order IS the served order, and appending is the only edit that
- * leaves the others where every existing declaration says they are.
+ * `memory_dream` after that, `token_ledger` after that and `work_plan` then `shiftwork_plan`
+ * after that, for the same reason the reference appends: registration order IS the served
+ * order, and appending is the only edit that leaves the others where every existing
+ * declaration says they are.
+ *
+ * `work_plan` BEFORE `shiftwork_plan` is the reference's order (`mcpserver.py`'s `tools`
+ * list), and it is load-bearing rather than alphabetical: `runtime-py/tests/data/
+ * served-tool-surface.json` pins the served order as a golden and `wire.mjs` compares the
+ * two `tools/list` answers frame by frame, so registering them the other way round is a
+ * red in three places and a wire change nobody asked for.
  *
  * `bantamkit_read` (tenth) and `repo_map` (thirteenth) LEFT this list on the user's ruling
  * of 2026-09-12 (job50, I5), the same ruling that took them out of the reference's
@@ -22,7 +29,7 @@ import type { RawStdioTransport } from './transport.js';
  * its argument model. The handlers below are DORMANT, not gone: a roster decision, not a
  * deletion of working code.
  */
-export declare const MCP_TOOLS: readonly ["memory_save", "memory_recall", "validate_json", "shiftwork_clock_in", "shiftwork_clock_out", "shiftwork_status", "build_identity", "bantamkit_status", "memory_compact", "skill_audit", "memory_dream", "token_ledger"];
+export declare const MCP_TOOLS: readonly ["memory_save", "memory_recall", "validate_json", "shiftwork_clock_in", "shiftwork_clock_out", "shiftwork_status", "build_identity", "bantamkit_status", "memory_compact", "skill_audit", "memory_dream", "token_ledger", "work_plan", "shiftwork_plan"];
 /**
  * The advertisement for one tool, out of its manifest, with the surface checked.
  *

package/dist/mcp/server.js

@@ -43,18 +43,26 @@ import { EventLog } from '../eventlog.js';
 import { PyOSError, asPyOSError, pyReadText } from '../memory/pyfs.js';
 import { fromJs, parseJson, reprValue, toJs } from '../pyjson.js';
 import * as shiftwork from '../shiftwork.js';
+import { plan } from '../workplan.js';
 import { buildIdentity, SERVER_NAME } from './identity.js';
 import { ARG_MODELS, PyValidationFailure, validateArguments } from './pyargs.js';
 import { sdkJson } from './sdkjson.js';
 import { degradedConditions, degradedNotice, SERVED_PROMPTS, SERVED_RESOURCE_TEMPLATES, statusReport, STATUS_NAME, STATUS_PROMPT_DESCRIPTION, STATUS_PROMPT_TAIL, STATUS_PROMPT_TITLE, } from './status.js';
 /**
- * The twelve, in the order `build_server` lists them — which is the order `tools/list` emits.
+ * The fourteen, in the order `build_server` lists them — which is the order `tools/list` emits.
  *
  * `bantamkit_status` went LAST rather than first, `memory_compact` after it rather than
  * beside `memory_save` where a reader would look for it, `skill_audit` after that,
- * `memory_dream` after that and `token_ledger` after that, for the same reason the reference
- * appends: registration order IS the served order, and appending is the only edit that
- * leaves the others where every existing declaration says they are.
+ * `memory_dream` after that, `token_ledger` after that and `work_plan` then `shiftwork_plan`
+ * after that, for the same reason the reference appends: registration order IS the served
+ * order, and appending is the only edit that leaves the others where every existing
+ * declaration says they are.
+ *
+ * `work_plan` BEFORE `shiftwork_plan` is the reference's order (`mcpserver.py`'s `tools`
+ * list), and it is load-bearing rather than alphabetical: `runtime-py/tests/data/
+ * served-tool-surface.json` pins the served order as a golden and `wire.mjs` compares the
+ * two `tools/list` answers frame by frame, so registering them the other way round is a
+ * red in three places and a wire change nobody asked for.
  *
  * `bantamkit_read` (tenth) and `repo_map` (thirteenth) LEFT this list on the user's ruling
  * of 2026-09-12 (job50, I5), the same ruling that took them out of the reference's
@@ -79,6 +87,8 @@ export const MCP_TOOLS = [
     'skill_audit',
     'memory_dream',
     'token_ledger',
+    'work_plan',
+    'shiftwork_plan',
 ];
 /** The served set, for the call path: a name outside it is unknown, whatever `ARG_MODELS` says. */
 const SERVED = new Set(MCP_TOOLS);
@@ -163,6 +173,44 @@ function rpcError(code, message, data) {
 }
 const asDict = (value) => (value.t === 'dict' ? value.v : new Map());
 const asText = (value) => (value && value.t === 'str' ? value.v : '');
+/**
+ * `work_plan`'s `nodes` as `workplan.plan` takes them.
+ *
+ * The reference's model is `list[dict[str, Any]]`, so pydantic guarantees a list of dicts
+ * and NOTHING about what is inside one; `workplan.plan` then reads `node["id"]`,
+ * `node.get("depends_on") or []` and `node.get("priority", 0)` off raw Python objects. This
+ * reproduces those three reads and their defaults.
+ *
+ * A NODE WITH NO `id` RAISES, and raising is the port: `node["id"]` is a `KeyError` on the
+ * reference, whose `str()` is the key in single quotes, so the SDK's envelope reads
+ * `Error executing tool work_plan: 'id'`. Defaulting it here would answer a plan over a
+ * node the reference refused to look at.
+ *
+ * WHERE THE DYNAMIC HALF STOPS, said rather than hidden. Python keeps an id's own type and
+ * this side stringifies it with `str()`'s spelling (`reprValue` for every non-`str`), so a
+ * document mixing `5` and `"5"` is two nodes there and one here, and a non-numeric
+ * `priority` is a `TypeError` there and a 0 here. Both need a node whose types contradict
+ * `assets/tools/work_plan.json`, which nothing in the shift-work corpus produces; they are
+ * named here because an unwritten difference is the one that is found later.
+ */
+function planNodes(value) {
+    const pyText = (v) => (v.t === 'str' ? v.v : reprValue(v));
+    const items = value !== undefined && value.t === 'list' ? value.v : [];
+    return items.map((item) => {
+        const node = item.t === 'dict' ? item.v : new Map();
+        const id = node.get('id');
+        if (id === undefined)
+            throw new BantamError("'id'");
+        const declared = node.get('depends_on');
+        const priority = node.get('priority');
+        return {
+            id: pyText(id),
+            // `list(node.get("depends_on") or [])`: missing, `null` and `[]` are one case.
+            depends_on: declared !== undefined && declared.t === 'list' ? declared.v.map(pyText) : [],
+            priority: priority !== undefined && (priority.t === 'int' || priority.t === 'float') ? Number(priority.v) : 0,
+        };
+    });
+}
 /** `int | None` after validation: the tagged int, or `null` for the default. */
 function asInt(value) {
     return value && value.t === 'int' ? Number(value.v) : null;
@@ -879,6 +927,47 @@ function runTool(name, memory, args, version, log, documents) {
                 return { value: { t: 'str', v: noted(tokenledger.asJson(result)) }, wrapped: true };
             });
         }
+        case 'work_plan':
+            // `depends_on` turned into the batches that may run in parallel, over any task list
+            // the caller hands over. No path, no file, no clock: `workplan.plan` is Layer 1 and
+            // this is the seam that serves it.
+            //
+            // `result` is added HERE and not in `workplan.plan`, which answers the COMPUTATION
+            // (`batches`, `sequence`, `width`) rather than a wire shape. The wire shape is the
+            // tool asset's, so the verdict key goes on at the seam that serves it — the same
+            // division `shiftwork.planBatches` uses one layer down. A refusal already carries its
+            // own `result` and passes through untouched, because `recordResult` reads that key to
+            // write the register's verdict to the log.
+            //
+            // THE MAPPING IS INSIDE THE CLOSURE, not above it, so that a node the core cannot
+            // read raises where the reference raises: within `_record_result`, which records the
+            // exception and re-raises it into the `Error executing tool work_plan:` envelope.
+            return {
+                value: notedDict(recordResult(log, name, () => {
+                    const answer = plan(planNodes(args.get('nodes')));
+                    if ('result' in answer)
+                        return { t: 'dict', v: new Map([['result', { t: 'str', v: 'error' }], ['reason', { t: 'str', v: answer.reason }]]) };
+                    return {
+                        t: 'dict',
+                        v: new Map([
+                            ['result', { t: 'str', v: 'plan' }],
+                            ['batches', { t: 'list', v: answer.batches.map((batch) => ({ t: 'list', v: batch.map((id) => ({ t: 'str', v: id })) })) }],
+                            ['sequence', { t: 'list', v: answer.sequence.map((id) => ({ t: 'str', v: id })) }],
+                            ['width', { t: 'int', v: BigInt(answer.width) }],
+                        ]),
+                    };
+                })),
+                wrapped: false,
+            };
+        case 'shiftwork_plan':
+            // The read-only batch view of a checkpoint. Registered beside `shiftwork_status`
+            // because it is the same kind of thing: a path in, an answer out, and not one byte
+            // written — `test/shiftwork.test.mjs` hashes the checkpoint AND its `.log.jsonl`
+            // before and after to hold that, rather than commenting it.
+            return {
+                value: notedDict(recordResult(log, name, () => shiftwork.planBatches(asText(args.get('checkpoint'))))),
+                wrapped: false,
+            };
         default:
             // `tool_manager.call_tool` raises `ToolError(f"Unknown tool: {name}")`, which the
             // handler turns into an isError result rather than a JSON-RPC error.

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/memory/cli.js

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

package/dist/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/shiftwork.d.ts

@@ -80,3 +80,36 @@ export declare function clockOut(checkpoint: string, unitId: string, status: str
  * The result is dumped without `sort_keys` on the wire, so that order is observable.
  */
 export declare function status(checkpoint: string): PyValue;
+/**
+ * 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.** `clockOut` 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: `readValid`'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.
+ */
+export declare function planBatches(checkpoint: string): PyValue;

package/dist/shiftwork.js

@@ -47,17 +47,24 @@
  * same place. That makes three refusal strings, not two, and the third is likewise a
  * per-side literal.
  *
- * WHAT IS NOT PORTED, DELIBERATELY. The `depends_on` field is ignored on cursor advance
- * (v1-linear, the Python module's own ruling), there is no lock (the MCP topology has one
- * orchestrator by construction), and log-then-commit ordering is preserved exactly: the
- * accounting line is appended BEFORE the atomic rename, so a partial failure can lose the
- * commit but never the accounting.
+ * WHAT IS NOT PORTED, DELIBERATELY. There is no lock (the MCP topology has one orchestrator
+ * by construction), and log-then-commit ordering is preserved exactly: the accounting line is
+ * appended BEFORE the atomic rename, so a partial failure can lose the commit but never the
+ * accounting.
+ *
+ * `depends_on` USED TO BE LISTED ABOVE, AND NO LONGER BELONGS THERE. `planBatches` below
+ * READS `depends_on` and answers the batch view, so the module no longer ignores the field;
+ * what still ignores it is CURSOR ADVANCE, which stays v1-linear (the Python module's own
+ * ruling) — it moves to the first non-terminal unit in `plan.units` order, and a non-linear
+ * plan still needs a planner unit to reorder `plan.units` first. The batch view is read-only
+ * and moves nothing.
  */
 import { AssetNotFound, loadSchema, loadToolAsset } from './assets.js';
 import { schemaError } from './contract.js';
 import { pyAppendText, pyJoin, PyOSError, pyReplace, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, pyReadText, PyUnicodeDecodeError, } from './memory/pyfs.js';
 import { dumpJson, fromJs, parseJson, PyJSONDecodeError, reprValue } from './pyjson.js';
 import { checkSchema, PyJsonSchemaUnsupported } from './pyjsonschema.js';
+import { plan } from './workplan.js';
 export const SCHEMA_NAME = 'shiftwork-checkpoint';
 /** The accounting line's shape lives on the TOOL asset, not in a second copy here (F5). */
 const TOOL_ASSET = 'shiftwork_clock_out';
@@ -692,3 +699,74 @@ export function status(checkpoint) {
         ['last_history', history.v.length > 0 ? history.v[history.v.length - 1] : { t: 'null' }],
     ]);
 }
+// ------------------------------------------------------------------------- plan_batches
+/**
+ * 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.** `clockOut` 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: `readValid`'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.
+ */
+export function planBatches(checkpoint) {
+    const { document, refusal } = readValid(pyJoin(checkpoint));
+    if (refusal !== null)
+        return refusal;
+    const doc = document;
+    const units = subList(subDict(doc, 'plan'), 'units').v;
+    const terminal = (unit) => TERMINAL_UNIT_STATUS.has(text(unit.v.get('status')));
+    const satisfied = new Set();
+    for (const unit of units) {
+        if (terminal(unit))
+            satisfied.add(text(unit.v.get('id')));
+    }
+    const nodes = [];
+    for (const unit of units) {
+        const u = unit;
+        if (terminal(u))
+            continue;
+        // `list(unit.get("depends_on") or [])`. `depends_on` is REQUIRED by the schema, so
+        // `readValid` has already refused a unit without it and this default cannot fire —
+        // it is written anyway because the reference writes it, and a default on one side
+        // only is how two runtimes come to disagree about real data.
+        const declared = u.v.get('depends_on');
+        const deps = declared !== undefined && declared.t === 'list' ? declared.v.map(text) : [];
+        nodes.push({ id: text(u.v.get('id')), depends_on: deps.filter((dep) => !satisfied.has(dep)), priority: 0 });
+    }
+    const answer = plan(nodes);
+    if ('result' in answer)
+        return errorResult(answer.reason);
+    const batches = answer.batches.map((batch) => ({ t: 'list', v: batch.map(str) }));
+    return dict([
+        ['result', str('plan')],
+        ['batches', { t: 'list', v: batches }],
+        ['ready', batches.length > 0 ? batches[0] : { t: 'list', v: [] }],
+        ['sequence', { t: 'list', v: answer.sequence.map(str) }],
+        ['width', int(answer.width)],
+        ['cursor', field(subDict(doc, 'plan'), 'cursor')],
+    ]);
+}

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/dist/workplan.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Layer 1 — the work-plan planner: `depends_on` turned into batches that may run in parallel.
+ *
+ * A pure function. No filesystem, no clock, no `mcp` import, no dependency: `docs/architecture.md`
+ * puts a deterministic graph planner in Core, and `shiftwork.ts` — which is Layer 5 — is the thing
+ * that will call it, not the thing it lives in.
+ *
+ * WHERE THE SEMANTICS COME FROM. `docs/superpowers/specs/2026-09-18-workplan-dag-design.md`. The
+ * user's own `ex-flow@1.1.0` measured the numbers in that spec, and it is deliberately NOT an
+ * install: `runtime-ts/package.json` declares exactly one runtime dependency,
+ * `@modelcontextprotocol/sdk`, and `docs/porting.md` uses "no runtime dependency is allowed into
+ * `runtime-ts`" as the live justification for three divergence rows. So `ex-flow` is the
+ * SPECIFICATION and this is one of two hand-written implementations held to it — the other being
+ * `runtime-py/src/bantamkit/workplan.py`, written independently so that
+ * `tools/conformance/suites/workplan.mjs` proves an agreement rather than a copy.
+ *
+ * WHAT IS DELIBERATELY LEFT OUT of `ex-flow`'s surface: `deadlineStrategy`, `weightStrategy`,
+ * `fairnessPolicy`/`maxDeferralRounds` aging, `schedulerMode: "throughput"`, `concurrencyCap`,
+ * `resourceCaps`, the clone modes and the config builder. None of the 19 measured checkpoints
+ * supplies a deadline, a weight or a resource class, so every one of them would be untested
+ * surface. `sequence` is `ex-flow`'s `fullSequence` under a shorter name.
+ *
+ * WHAT THIS DOES NOT CLAIM. `depends_on` encodes logical order, not file contention. Measured on
+ * `.shiftwork/checkpoint-job44.json`, whose first batch is twelve units wide, seven of those
+ * twelve name `runtime-ts/src/docread.ts`. The graph says they may run in parallel; the filesystem
+ * does not. This function reports what the graph permits and the orchestrator stays responsible
+ * for what it actually dispatches.
+ */
+/** One task. `priority` is optional and absent means `0` — the checkpoint schema has no such field. */
+export interface PlanNode {
+    id: string;
+    depends_on: string[];
+    priority?: number;
+}
+/** A plan: the batches, the same ids read end to end, and the widest fan-out in the plan. */
+export interface PlanOk {
+    batches: string[][];
+    sequence: string[];
+    width: number;
+}
+/**
+ * A refusal, in the `{result, reason}` shape `shiftwork` already returns, so nothing new is
+ * invented for it. The three sentences are pinned per-side in `test/workplan.test.mjs` because a
+ * sentence both runtimes copied is invisible to the differential.
+ */
+export interface PlanError {
+    result: 'error';
+    reason: string;
+}
+export type PlanResult = PlanOk | PlanError;
+/**
+ * Level-synchronous Kahn: batch *k* holds every node whose dependencies all appear in batches < *k*.
+ *
+ * **Empty input is not an error.** `plan([])` is `{batches: [], sequence: [], width: 0}` — a plan
+ * with nothing left to do is the answer, the same reasoning `clock_in` applies when an all-terminal
+ * checkpoint reports success rather than escalating on a dangling cursor.
+ *
+ * **The three refusals are checked in a fixed order** — duplicate id, then unknown dependency, then
+ * cycle — because a graph can carry two faults at once and both runtimes have to name the same one.
+ */
+export declare function plan(nodes: readonly PlanNode[]): PlanResult;

package/dist/workplan.js

@@ -0,0 +1,126 @@
+/**
+ * Layer 1 — the work-plan planner: `depends_on` turned into batches that may run in parallel.
+ *
+ * A pure function. No filesystem, no clock, no `mcp` import, no dependency: `docs/architecture.md`
+ * puts a deterministic graph planner in Core, and `shiftwork.ts` — which is Layer 5 — is the thing
+ * that will call it, not the thing it lives in.
+ *
+ * WHERE THE SEMANTICS COME FROM. `docs/superpowers/specs/2026-09-18-workplan-dag-design.md`. The
+ * user's own `ex-flow@1.1.0` measured the numbers in that spec, and it is deliberately NOT an
+ * install: `runtime-ts/package.json` declares exactly one runtime dependency,
+ * `@modelcontextprotocol/sdk`, and `docs/porting.md` uses "no runtime dependency is allowed into
+ * `runtime-ts`" as the live justification for three divergence rows. So `ex-flow` is the
+ * SPECIFICATION and this is one of two hand-written implementations held to it — the other being
+ * `runtime-py/src/bantamkit/workplan.py`, written independently so that
+ * `tools/conformance/suites/workplan.mjs` proves an agreement rather than a copy.
+ *
+ * WHAT IS DELIBERATELY LEFT OUT of `ex-flow`'s surface: `deadlineStrategy`, `weightStrategy`,
+ * `fairnessPolicy`/`maxDeferralRounds` aging, `schedulerMode: "throughput"`, `concurrencyCap`,
+ * `resourceCaps`, the clone modes and the config builder. None of the 19 measured checkpoints
+ * supplies a deadline, a weight or a resource class, so every one of them would be untested
+ * surface. `sequence` is `ex-flow`'s `fullSequence` under a shorter name.
+ *
+ * WHAT THIS DOES NOT CLAIM. `depends_on` encodes logical order, not file contention. Measured on
+ * `.shiftwork/checkpoint-job44.json`, whose first batch is twelve units wide, seven of those
+ * twelve name `runtime-ts/src/docread.ts`. The graph says they may run in parallel; the filesystem
+ * does not. This function reports what the graph permits and the orchestrator stays responsible
+ * for what it actually dispatches.
+ */
+const refuse = (reason) => ({ result: 'error', reason });
+/**
+ * Name the cycle that stopped Kahn, deterministically.
+ *
+ * Two runtimes left to their own devices will name two different — equally correct — cycles in the
+ * same graph, and the conformance suite goes red for a reason that is not a defect. The rule, and
+ * the three rulings that disambiguate it:
+ *
+ * - Scan the nodes Kahn could not emit **in input order** and start at the first.
+ * - Walk `depends_on` **in declared order**, following only dependencies that are themselves
+ *   UN-EMITTED. A dependency already emitted in an earlier batch can never close a cycle, so
+ *   following it would dead-end on a graph that does have one. (Every un-emitted node has at least
+ *   one un-emitted dependency — otherwise it was ready — so the walk can never run out of edges.)
+ * - The first repeated id closes the cycle, and the reported path is the CYCLE, not the whole walk:
+ *   the scan may have started merely downstream of the loop, and a sentence that named a node
+ *   outside the loop would be describing something other than the cycle it claims to name.
+ */
+function cyclePath(nodes, emitted) {
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const path = [];
+    /** id -> where it sits in `path`, which is what turns "seen before" into "trim the tail here". */
+    const at = new Map();
+    let current = nodes.find((node) => !emitted.has(node.id));
+    while (current !== undefined) {
+        const repeat = at.get(current.id);
+        if (repeat !== undefined)
+            return [...path.slice(repeat), current.id];
+        at.set(current.id, path.length);
+        path.push(current.id);
+        const next = current.depends_on.find((dep) => !emitted.has(dep));
+        current = next === undefined ? undefined : byId.get(next);
+    }
+    // Unreachable on a graph that reached here: the walk only ends by repeating an id.
+    return path;
+}
+/**
+ * Level-synchronous Kahn: batch *k* holds every node whose dependencies all appear in batches < *k*.
+ *
+ * **Empty input is not an error.** `plan([])` is `{batches: [], sequence: [], width: 0}` — a plan
+ * with nothing left to do is the answer, the same reasoning `clock_in` applies when an all-terminal
+ * checkpoint reports success rather than escalating on a dangling cursor.
+ *
+ * **The three refusals are checked in a fixed order** — duplicate id, then unknown dependency, then
+ * cycle — because a graph can carry two faults at once and both runtimes have to name the same one.
+ */
+export function plan(nodes) {
+    // 1 — duplicate id. First in input order wins.
+    const declared = new Set();
+    for (const node of nodes) {
+        if (declared.has(node.id))
+            return refuse(`duplicate node id ${node.id}`);
+        declared.add(node.id);
+    }
+    // 2 — a dependency nothing declares. First node in input order, first dep in declared order.
+    for (const node of nodes) {
+        for (const dep of node.depends_on) {
+            if (!declared.has(dep)) {
+                return refuse(`node ${node.id} depends on ${dep}, which no node declares`);
+            }
+        }
+    }
+    // 3 — the batches.
+    const emitted = new Set();
+    const batches = [];
+    const sequence = [];
+    let width = 0;
+    while (emitted.size < nodes.length) {
+        /**
+         * Carry the input index explicitly rather than leaning on `Array.prototype.sort` being stable.
+         * It is, in every Node this package supports — but the tie-break is the thing the conformance
+         * gate compares against Python, and a reader has to be able to SEE that it is insertion order
+         * and not a property of the sort.
+         */
+        const ready = [];
+        for (const [index, node] of nodes.entries()) {
+            if (emitted.has(node.id))
+                continue;
+            if (node.depends_on.every((dep) => emitted.has(dep))) {
+                ready.push({ id: node.id, priority: node.priority ?? 0, index });
+            }
+        }
+        // Nothing is ready and something is left: the remainder contains a cycle.
+        if (ready.length === 0) {
+            return refuse(`the graph has a cycle: ${cyclePath(nodes, emitted).join(' -> ')}`);
+        }
+        // Priority descending, then insertion order.
+        ready.sort((a, b) => b.priority - a.priority || a.index - b.index);
+        const batch = ready.map((entry) => entry.id);
+        batches.push(batch);
+        for (const id of batch) {
+            emitted.add(id);
+            sequence.push(id);
+        }
+        if (batch.length > width)
+            width = batch.length;
+    }
+    return { batches, sequence, width };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bantamkit-mcp",
-  "version": "0.35.0",
+  "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",
@@ -44,7 +44,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "sync-assets": "node scripts/sync-assets.mjs",
-    "prepack": "node scripts/sync-assets.mjs",
+    "prepack": "node scripts/build-for-pack.mjs && npm run sync-assets",
+    "prepublishOnly": "node scripts/gate-before-publish.mjs",
     "pretest": "npm run build",
     "test": "node scripts/run-tests.mjs"
   },