@listen-fire/module-runtime 0.12.0-rc.8 → 0.12.0

package/dist/module_wire/conformance.d.ts

@@ -42,3 +42,11 @@ export declare const secretsSlotCases: SlotConformanceCase[];
  *  answers: `client` reaches one. Entries are refused by name with a reason;
  *  everything a refresh needs still works. */
 export declare const secretsReadOnlySlotCases: SlotConformanceCase[];
+/** The movements slot's own cases (docs/contracts/movements-slot.md): the
+ *  list, a read of nothing, writes by compare-and-swap on the version, the
+ *  path rule. `client` reaches a module that can change its files. */
+export declare const movementsSlotCases: SlotConformanceCase[];
+/** What a module that keeps the project's movements where lf cannot change
+ *  them answers: `client` reaches one. A write is refused by name with a
+ *  reason; listing and reading still work. */
+export declare const movementsReadOnlySlotCases: SlotConformanceCase[];

package/dist/module_wire/conformance.js

@@ -1,6 +1,6 @@
 "use strict";
 // The conformance suites of the slots with no family contract of their own
-// (models, judge, files, wake, ocr), and the secrets slot's own cases beside
+// (models, judge, files, wake, ocr), the movements slot's, and the secrets slot's own cases beside
 // the family's (`services/secrets/contract.ts`), and the cases every slot module answers alike (its
 // manifest, the envelope's refusals). Each runs against any server over the
 // wire: written once here, they hold lf's built-ins (`lf --contract-<slot>`)
@@ -10,7 +10,7 @@
 // `loop_guard/contract.ts`) driven over this same wire; the browser to
 // `services/browser/contract.ts` through its wire client.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.secretsReadOnlySlotCases = exports.secretsSlotCases = exports.wakeSlotCases = exports.ocrSlotCases = exports.filesSlotCases = exports.judgeSlotCases = exports.modelsSlotCases = void 0;
+exports.movementsReadOnlySlotCases = exports.movementsSlotCases = exports.secretsReadOnlySlotCases = exports.secretsSlotCases = exports.wakeSlotCases = exports.ocrSlotCases = exports.filesSlotCases = exports.judgeSlotCases = exports.modelsSlotCases = void 0;
 exports.commonSlotCases = commonSlotCases;
 const node_assert_1 = require("node:assert");
 const node_crypto_1 = require("node:crypto");
@@ -451,3 +451,129 @@ exports.secretsReadOnlySlotCases = [
         },
     },
 ];
+// ── The movements slot ──────────────────────────────────────────────────────
+const NEW_MOVEMENT = () => `conformance/${(0, node_crypto_1.randomUUID)()}.mvt`;
+async function listedMovements(client) {
+    return client.read('movements.list', {}, slots_1.MovementsListAnswer);
+}
+const writeMovement = (client, path, text, expectedVersion) => client.read('movements.write', { path, text, expectedVersion }, slots_1.MovementsWriteAnswer);
+/** Creates a file and returns the version it was written at. */
+async function createdMovement(client, path, text) {
+    const made = await writeMovement(client, path, text, null);
+    node_assert_1.strict.equal(made.kind, 'written', `creating ${path} answered ${JSON.stringify(made)}`);
+    return made.kind === 'written' ? made.version : '';
+}
+/** The movements slot's own cases (docs/contracts/movements-slot.md): the
+ *  list, a read of nothing, writes by compare-and-swap on the version, the
+ *  path rule. `client` reaches a module that can change its files. */
+exports.movementsSlotCases = [
+    {
+        name: 'movements: list names a created file, and its version is the one read answers',
+        async run(client) {
+            const path = NEW_MOVEMENT();
+            const version = await createdMovement(client, path, 'movement hello {}\n');
+            const one = (await listedMovements(client)).find((file) => file.path === path);
+            node_assert_1.strict.ok(one !== undefined, 'a created file is listed');
+            node_assert_1.strict.ok(one.version === undefined || one.version === version, 'a listed version is the one the write answered');
+            node_assert_1.strict.deepEqual(await client.read('movements.read', { path }, slots_1.MovementsReadAnswer), { text: 'movement hello {}\n', version });
+        },
+    },
+    {
+        name: 'movements: read of a path with nothing at it answers null',
+        async run(client) {
+            node_assert_1.strict.equal(await client.call('movements.read', { path: NEW_MOVEMENT() }), null);
+        },
+    },
+    {
+        name: 'movements: create with a null expectedVersion writes; a second create answers conflict with the current version and changes nothing',
+        async run(client) {
+            const path = NEW_MOVEMENT();
+            const version = await createdMovement(client, path, 'one');
+            node_assert_1.strict.deepEqual(await writeMovement(client, path, 'two', null), { kind: 'conflict', current: version });
+            node_assert_1.strict.equal((await client.read('movements.read', { path }, slots_1.MovementsReadAnswer))?.text, 'one', 'the refused create changed nothing');
+        },
+    },
+    {
+        name: 'movements: replace with the current version answers a new version, and the text reads back byte for byte',
+        async run(client) {
+            const path = NEW_MOVEMENT();
+            const first = await createdMovement(client, path, 'one');
+            const text = 'movement caf\u00e9 {}\n\u00fcber \u2713\n';
+            const replaced = await writeMovement(client, path, text, first);
+            node_assert_1.strict.equal(replaced.kind, 'written');
+            node_assert_1.strict.ok(replaced.kind === 'written' && replaced.version !== first, 'a replace is a new version');
+            const read = await client.read('movements.read', { path }, slots_1.MovementsReadAnswer);
+            node_assert_1.strict.equal(read?.text, text);
+            node_assert_1.strict.equal(read?.version, replaced.kind === 'written' ? replaced.version : undefined);
+        },
+    },
+    {
+        name: 'movements: a stale version answers conflict with the current one and changes nothing; so does a version for a path with nothing at it',
+        async run(client) {
+            const path = NEW_MOVEMENT();
+            const first = await createdMovement(client, path, 'one');
+            const second = await writeMovement(client, path, 'two', first);
+            node_assert_1.strict.equal(second.kind, 'written');
+            const current = second.kind === 'written' ? second.version : '';
+            node_assert_1.strict.deepEqual(await writeMovement(client, path, 'three', first), { kind: 'conflict', current });
+            node_assert_1.strict.equal((await client.read('movements.read', { path }, slots_1.MovementsReadAnswer))?.text, 'two');
+            node_assert_1.strict.deepEqual(await writeMovement(client, NEW_MOVEMENT(), 'x', 'no-such-version'), { kind: 'conflict', current: null });
+        },
+    },
+    {
+        name: 'movements: the same text listed twice keeps its version; a changed text changes it',
+        async run(client) {
+            const path = NEW_MOVEMENT();
+            await createdMovement(client, path, 'one');
+            const versionOf = async () => (await client.read('movements.read', { path }, slots_1.MovementsReadAnswer))?.version;
+            const before = await versionOf();
+            node_assert_1.strict.equal(await versionOf(), before, 'reading twice does not change the version');
+            const listedVersion = async () => (await listedMovements(client)).find((file) => file.path === path)?.version;
+            node_assert_1.strict.equal(await listedVersion(), await listedVersion(), 'listing twice does not change it');
+            node_assert_1.strict.ok(before !== undefined);
+            await writeMovement(client, path, 'two', before);
+            node_assert_1.strict.notEqual(await versionOf(), before, 'a changed text is a new version');
+        },
+    },
+    {
+        name: 'movements: a path that is not relative, `/`-separated and ending .mvt is refused as bad_request on read and write',
+        async run(client) {
+            for (const path of ['/a.mvt', 'a/../b.mvt', './a.mvt', 'a//b.mvt', 'a\\b.mvt', 'a.txt', 'a']) {
+                await refusedWith('bad_request', client.call('movements.read', { path }));
+                await refusedWith('bad_request', client.call('movements.write', { path, text: 'x', expectedVersion: null }));
+            }
+            await refusedWith('bad_request', client.call('movements.read', {}));
+        },
+    },
+    {
+        name: 'movements: a write without its expectedVersion, or without its text, is refused as bad_request and writes nothing',
+        async run(client) {
+            const path = NEW_MOVEMENT();
+            await refusedWith('bad_request', client.call('movements.write', { path, text: 'x' }));
+            await refusedWith('bad_request', client.call('movements.write', { path, expectedVersion: null }));
+            node_assert_1.strict.equal(await client.call('movements.read', { path }), null);
+        },
+    },
+];
+/** What a module that keeps the project's movements where lf cannot change
+ *  them answers: `client` reaches one. A write is refused by name with a
+ *  reason; listing and reading still work. */
+exports.movementsReadOnlySlotCases = [
+    {
+        name: 'movements: a read-only module answers movements.write with read_only and its reason, and keeps nothing',
+        async run(client) {
+            const path = NEW_MOVEMENT();
+            const answer = await writeMovement(client, path, 'one', null);
+            node_assert_1.strict.ok(answer.kind === 'read_only' && answer.reason.length > 0, `movements.write answered ${JSON.stringify(answer)}`);
+            node_assert_1.strict.equal(await client.call('movements.read', { path }), null);
+            node_assert_1.strict.equal((await listedMovements(client)).find((file) => file.path === path), undefined);
+        },
+    },
+    {
+        name: 'movements: a read-only module still lists and reads',
+        async run(client) {
+            node_assert_1.strict.ok(Array.isArray(await client.call('movements.list', {})));
+            node_assert_1.strict.equal(await client.call('movements.read', { path: NEW_MOVEMENT() }), null);
+        },
+    },
+];

package/dist/module_wire/wire.d.ts

@@ -60,6 +60,15 @@ export declare class SlotRefusal extends Error {
     readonly data?: unknown;
     constructor(code: string, message: string, data?: unknown);
 }
+/** The envelope rules for one request whose body is already read as JSON,
+ *  without a server: the manifest answer, the protocol version refusal, an
+ *  unknown method and a module's `SlotRefusal` codes, a malformed body.
+ *  `serveSlot` answers every request through it, and a host router (the
+ *  platform's routes) applies the same rules by calling it. */
+export declare function answerSlotRequest(manifest: WireSlotManifestShape, answer: SlotAnswer, body: unknown): Promise<{
+    status: number;
+    body: unknown;
+}>;
 export interface ServedSlot {
     address: SlotAddress;
     close(): Promise<void>;

package/dist/module_wire/wire.js

@@ -10,6 +10,7 @@ exports.postTo = postTo;
 exports.listeningAddress = listeningAddress;
 exports.freshSocketPath = freshSocketPath;
 exports.startModule = startModule;
+exports.answerSlotRequest = answerSlotRequest;
 exports.serveSlot = serveSlot;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
@@ -191,6 +192,41 @@ class SlotRefusal extends Error {
     }
 }
 exports.SlotRefusal = SlotRefusal;
+/** The envelope rules for one request whose body is already read as JSON,
+ *  without a server: the manifest answer, the protocol version refusal, an
+ *  unknown method and a module's `SlotRefusal` codes, a malformed body.
+ *  `serveSlot` answers every request through it, and a host router (the
+ *  platform's routes) applies the same rules by calling it. */
+async function answerSlotRequest(manifest, answer, body) {
+    const envelope = slots_1.SlotRequestEnvelope.safeParse(body);
+    if (!envelope.success) {
+        const version = body !== null && typeof body === 'object' ? Reflect.get(body, 'protocolVersion') : undefined;
+        if (version !== undefined && version !== engine_contracts_1.PROTOCOL_VERSION) {
+            return { status: 200, body: { ok: false, error: { code: 'protocol_version', message: `this module speaks protocol ${engine_contracts_1.PROTOCOL_VERSION}`, retryable: false } } };
+        }
+        return { status: 400, body: { error: 'bad_request' } };
+    }
+    const { method, params, settings } = envelope.data;
+    try {
+        const result = method === 'manifest' ? manifest : await answer(method, params, settings ?? {});
+        return { status: 200, body: { ok: true, result: result ?? null } };
+    }
+    catch (error) {
+        const refusal = error instanceof SlotRefusal ? error : undefined;
+        return {
+            status: 200,
+            body: {
+                ok: false,
+                error: {
+                    code: refusal?.code ?? 'module_error',
+                    message: error instanceof Error ? error.message : String(error),
+                    retryable: refusal === undefined,
+                    ...(refusal?.data !== undefined ? { data: refusal.data } : {}),
+                },
+            },
+        };
+    }
+}
 /** Serve `answer` as a module of `manifest`'s slot. `listen`: a socket path
  *  or a port; default `MODULE_SOCKET`, else `PORT`, else a fresh socket.
  *  `MODULE_TOKEN` (or `token`) is required on every request when set. */
@@ -214,31 +250,8 @@ function serveSlot(options) {
         catch {
             return reply(response, 400, { error: 'bad_request' });
         }
-        const envelope = slots_1.SlotRequestEnvelope.safeParse(json);
-        if (!envelope.success) {
-            const version = json !== null && typeof json === 'object' ? Reflect.get(json, 'protocolVersion') : undefined;
-            if (version !== undefined && version !== engine_contracts_1.PROTOCOL_VERSION) {
-                return reply(response, 200, { ok: false, error: { code: 'protocol_version', message: `this module speaks protocol ${engine_contracts_1.PROTOCOL_VERSION}`, retryable: false } });
-            }
-            return reply(response, 400, { error: 'bad_request' });
-        }
-        const { method, params, settings } = envelope.data;
-        try {
-            const result = method === 'manifest' ? options.manifest : await options.answer(method, params, settings ?? {});
-            reply(response, 200, { ok: true, result: result ?? null });
-        }
-        catch (error) {
-            const refusal = error instanceof SlotRefusal ? error : undefined;
-            reply(response, 200, {
-                ok: false,
-                error: {
-                    code: refusal?.code ?? 'module_error',
-                    message: error instanceof Error ? error.message : String(error),
-                    retryable: refusal === undefined,
-                    ...(refusal?.data !== undefined ? { data: refusal.data } : {}),
-                },
-            });
-        }
+        const answered = await answerSlotRequest(options.manifest, options.answer, json);
+        reply(response, answered.status, answered.body);
     };
     const fromEnv = (process.env.MODULE_SOCKET || undefined) ?? (process.env.PORT ? Number(process.env.PORT) : undefined);
     const listen = options.listen ?? fromEnv ?? freshSocketPath() ?? 0;

package/dist/vendor_wait.d.ts

@@ -6,3 +6,21 @@
  * neither spin nor stall a caller.
  */
 export declare function vendorWaitMs(e: unknown, now?: number): number | undefined;
+/** What a vendor reports of its own budget on a success. */
+export interface VendorBudget {
+    /** Calls (or tokens) the vendor says are left in its window. */
+    remaining: number;
+    /** Epoch ms when that window resets. */
+    resetAt: number;
+}
+/**
+ * The budget a vendor reported on a success, from its rate-limit headers
+ * (`headers`: a plain object or `Headers`): Anthropic's
+ * `anthropic-ratelimit-{requests,tokens}-{remaining,reset}` and OpenAI's
+ * `x-ratelimit-{remaining,reset}-{requests,tokens}`. When several limits
+ * report, the one that binds: an exhausted one (the latest reset among them),
+ * else the least remaining. Undefined when no family gave both a count and a
+ * reset. The reset is clamped to at most 120s ahead, as `vendorWaitMs` clamps
+ * a wait.
+ */
+export declare function vendorBudget(headers: unknown, now?: number): VendorBudget | undefined;

package/dist/vendor_wait.js

@@ -4,6 +4,7 @@
 // limiter (`throttleAfter`, movement-engine/public/limiter) read one parser.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.vendorWaitMs = vendorWaitMs;
+exports.vendorBudget = vendorBudget;
 const SECOND = 1000;
 const MIN_WAIT_MS = 1 * SECOND;
 const MAX_WAIT_MS = 120 * SECOND;
@@ -62,3 +63,57 @@ function vendorWaitMs(e, now = Date.now()) {
     const fromBody = text === undefined ? undefined : fromRetryInfo(text);
     return fromBody === undefined ? undefined : clamp(fromBody);
 }
+/** Each family of success headers: the remaining count, and when it resets. */
+const BUDGET_FAMILIES = [
+    { remaining: 'anthropic-ratelimit-requests-remaining', reset: 'anthropic-ratelimit-requests-reset' },
+    { remaining: 'anthropic-ratelimit-tokens-remaining', reset: 'anthropic-ratelimit-tokens-reset' },
+    { remaining: 'x-ratelimit-remaining-requests', reset: 'x-ratelimit-reset-requests' },
+    { remaining: 'x-ratelimit-remaining-tokens', reset: 'x-ratelimit-reset-tokens' },
+];
+const DURATION_UNIT_MS = { ms: 1, s: SECOND, m: 60 * SECOND, h: 3600 * SECOND };
+/** OpenAI's reset form: a Go-style duration, `"1s"`, `"6m0s"`, `"20ms"`. */
+function fromDuration(text) {
+    const parts = [...text.matchAll(/(\d+(?:\.\d+)?)(ms|h|m|s)/g)];
+    if (parts.length === 0 || parts.map((part) => part[0]).join('') !== text)
+        return undefined;
+    return parts.reduce((total, [, amount, unit]) => total + Number(amount) * (DURATION_UNIT_MS[unit] ?? 0), 0);
+}
+/** A reset as an epoch ms: an ISO timestamp (Anthropic), whole or fractional
+ *  seconds from now, or a duration from now (OpenAI). */
+function resetInstant(value, now) {
+    const text = value.trim();
+    if (/^\d+(\.\d+)?$/.test(text))
+        return now + Number(text) * SECOND;
+    const duration = fromDuration(text);
+    if (duration !== undefined)
+        return now + duration;
+    const date = Date.parse(text);
+    return Number.isNaN(date) ? undefined : date;
+}
+/**
+ * The budget a vendor reported on a success, from its rate-limit headers
+ * (`headers`: a plain object or `Headers`): Anthropic's
+ * `anthropic-ratelimit-{requests,tokens}-{remaining,reset}` and OpenAI's
+ * `x-ratelimit-{remaining,reset}-{requests,tokens}`. When several limits
+ * report, the one that binds: an exhausted one (the latest reset among them),
+ * else the least remaining. Undefined when no family gave both a count and a
+ * reset. The reset is clamped to at most 120s ahead, as `vendorWaitMs` clamps
+ * a wait.
+ */
+function vendorBudget(headers, now = Date.now()) {
+    const reports = [];
+    for (const family of BUDGET_FAMILIES) {
+        const left = readHeader(headers, family.remaining)?.trim();
+        const reset = readHeader(headers, family.reset);
+        if (left === undefined || reset === undefined || !/^\d+$/.test(left))
+            continue;
+        const resetAt = resetInstant(reset, now);
+        if (resetAt === undefined)
+            continue;
+        reports.push({ remaining: Number(left), resetAt: Math.min(resetAt, now + MAX_WAIT_MS) });
+    }
+    const exhausted = reports.filter((report) => report.remaining === 0);
+    if (exhausted.length > 0)
+        return exhausted.reduce((latest, report) => (report.resetAt > latest.resetAt ? report : latest));
+    return reports.reduce((least, report) => (least === undefined || report.remaining < least.remaining ? report : least), undefined);
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@listen-fire/module-runtime",
   "license": "Apache-2.0",
-  "version": "0.12.0-rc.8",
+  "version": "0.12.0",
   "description": "What a module and the host that loads it share at run time on Node, beside the runtime-neutral contracts (@listen-fire/engine-contracts): a live adapter's file bytes as a stream, the files slot, the secrets family with the generic OAuth 2 refresh and connect, the in-memory vault, the browser slot and a bounded concurrency queue. The engine and the module kit both depend on it, so the kit never depends on the engine",
   "engines": {
-    "node": "22.20.0"
+    "node": ">=22.23.4 <23"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -22,7 +22,7 @@
   "type": "commonjs",
   "dependencies": {
     "zod": "4.1.12",
-    "@listen-fire/engine-contracts": "^0.12.0-rc.8"
+    "@listen-fire/engine-contracts": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "20.16.5",
@@ -37,8 +37,7 @@
     "dist"
   ],
   "publishConfig": {
-    "access": "public",
-    "tag": "next"
+    "access": "public"
   },
   "scripts": {
     "code:type-check": "tsc --pretty --noEmit && node ../../scripts/check-module-boundary.cjs"