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

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from './secrets/connect';
 export * from './secrets/family';
 export * from './secrets/memory';
 export * from './secrets/oauth2';
+export * from './vendor_wait';

package/dist/index.js

@@ -4,7 +4,8 @@
 // bytes as a stream, the files slot, the secrets family (resolve a credential,
 // write it back at a version, refresh it once at a time) with the generic
 // OAuth 2 refresh and connect, the in-memory vault an embedder starts from,
-// the browser slot, and a bounded concurrency queue.
+// the browser slot, a bounded concurrency queue, and how long a
+// rate-limited vendor asked to wait.
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -28,3 +29,4 @@ __exportStar(require("./secrets/connect"), exports);
 __exportStar(require("./secrets/family"), exports);
 __exportStar(require("./secrets/memory"), exports);
 __exportStar(require("./secrets/oauth2"), exports);
+__exportStar(require("./vendor_wait"), exports);

package/dist/module-wire.d.ts

@@ -2,3 +2,4 @@ export * from './module_wire/wire';
 export * from './module_wire/conformance';
 export * from './module_wire/browser';
 export * from './module_wire/scanned';
+export * from './module_wire/secrets';

package/dist/module-wire.js

@@ -24,3 +24,4 @@ __exportStar(require("./module_wire/wire"), exports);
 __exportStar(require("./module_wire/conformance"), exports);
 __exportStar(require("./module_wire/browser"), exports);
 __exportStar(require("./module_wire/scanned"), exports);
+__exportStar(require("./module_wire/secrets"), exports);

package/dist/module_wire/conformance.d.ts

@@ -33,3 +33,20 @@ export interface WakeConformanceCase {
 }
 /** The wake slot (docs/contracts/wake-slot.md). */
 export declare const wakeSlotCases: WakeConformanceCase[];
+/** The secrets slot's own cases (docs/contracts/secrets-slot.md): the list,
+ *  the lease and whole entries. `client` reaches a module that can change its
+ *  entries; the family's cases (`secretsContractCases`) hold its resolve and
+ *  write-back to the meaning every store has. */
+export declare const secretsSlotCases: SlotConformanceCase[];
+/** What a module that keeps its credentials where lf cannot change them
+ *  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,7 @@
 "use strict";
 // The conformance suites of the slots with no family contract of their own
-// (models, judge, files, wake, ocr), and the cases every slot module answers alike (its
+// (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>`)
 // and a third-party module in any language to the same meaning. The store,
@@ -9,12 +10,14 @@
 // `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.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");
 const engine_contracts_1 = require("@listen-fire/engine-contracts");
 const slots_1 = require("@listen-fire/engine-contracts/slots");
 const scanned_1 = require("./scanned");
+const zod_1 = require("zod");
 const wire_1 = require("./wire");
 async function refusedWith(code, call) {
     try {
@@ -314,3 +317,263 @@ exports.wakeSlotCases = [
         },
     },
 ];
+// ── The secrets slot ────────────────────────────────────────────────────────
+const NEW_REF = () => `conf_${(0, node_crypto_1.randomUUID)().replaceAll('-', '').slice(0, 12)}`;
+const SecretsList = zod_1.z.array(slots_1.SecretsListed);
+async function listed(client) {
+    return client.read('secrets.list', {}, SecretsList);
+}
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+/** The secrets slot's own cases (docs/contracts/secrets-slot.md): the list,
+ *  the lease and whole entries. `client` reaches a module that can change its
+ *  entries; the family's cases (`secretsContractCases`) hold its resolve and
+ *  write-back to the meaning every store has. */
+exports.secretsSlotCases = [
+    {
+        name: 'secrets: list names each credential with its external, binding and the version resolve answers',
+        async run(client) {
+            const ref = NEW_REF();
+            const binding = { credential: 'oauth' };
+            await client.read('secrets.create', { ref, external: 'acme_crm', binding, fields: { access_token: 'a1', workspace: 'w1' } }, slots_1.SecretsEntryAnswer);
+            const one = (await listed(client)).find((entry) => entry.ref === ref);
+            node_assert_1.strict.ok(one !== undefined, 'a created entry is listed');
+            node_assert_1.strict.equal(one.external, 'acme_crm');
+            node_assert_1.strict.deepEqual(one.binding, binding);
+            node_assert_1.strict.equal(one.version, (await client.read('secrets.resolve', { ref }, slots_1.SecretsRecord.nullable()))?.version);
+            await client.call('secrets.delete', { ref });
+        },
+    },
+    {
+        name: 'secrets: create, replace and delete change whole entries, each answered null',
+        async run(client) {
+            const ref = NEW_REF();
+            node_assert_1.strict.equal(await client.call('secrets.create', { ref, external: 'acme_crm', binding: 'legacy', fields: { api_key: 'k1' } }), null);
+            node_assert_1.strict.deepEqual((await client.read('secrets.resolve', { ref }, slots_1.SecretsRecord.nullable()))?.fields, { api_key: 'k1' });
+            node_assert_1.strict.equal(await client.call('secrets.replace', { ref, external: 'acme_crm', binding: 'install', fields: { api_key: 'k2', workspace: 'w2' } }), null);
+            node_assert_1.strict.deepEqual((await client.read('secrets.resolve', { ref }, slots_1.SecretsRecord.nullable()))?.fields, { api_key: 'k2', workspace: 'w2' }, 'replace is the whole entry, not a merge');
+            node_assert_1.strict.equal((await listed(client)).find((entry) => entry.ref === ref)?.binding, 'install');
+            node_assert_1.strict.equal(await client.call('secrets.delete', { ref }), null);
+            node_assert_1.strict.equal(await client.call('secrets.resolve', { ref }), null);
+            node_assert_1.strict.equal((await listed(client)).find((entry) => entry.ref === ref), undefined, 'a deleted entry is not listed');
+        },
+    },
+    {
+        name: 'secrets: create of an entry that exists, and delete of one that does not, are refused',
+        async run(client) {
+            const ref = NEW_REF();
+            const entry = { ref, external: 'acme_crm', binding: 'legacy', fields: { api_key: 'k1' } };
+            await client.call('secrets.create', entry);
+            await node_assert_1.strict.rejects(client.call('secrets.create', { ...entry, fields: { api_key: 'k9' } }), wire_1.SlotRefused);
+            node_assert_1.strict.equal((await client.read('secrets.resolve', { ref }, slots_1.SecretsRecord.nullable()))?.fields.api_key, 'k1', 'the refused create changed nothing');
+            await client.call('secrets.delete', { ref });
+            await node_assert_1.strict.rejects(client.call('secrets.delete', { ref }), wire_1.SlotRefused);
+        },
+    },
+    {
+        name: 'secrets: a second lock on a credential while one is held answers null; unlock frees it',
+        async run(client) {
+            const ref = NEW_REF();
+            const held = await client.read('secrets.lock', { ref, ttlMs: 30_000 }, slots_1.SecretsLockAnswer);
+            node_assert_1.strict.ok(held !== null, 'a free credential is locked');
+            node_assert_1.strict.equal(await client.call('secrets.lock', { ref, ttlMs: 30_000 }), null);
+            node_assert_1.strict.equal(await client.call('secrets.unlock', { ref, token: `${held.token}-not` }), null, 'a token that is not the lease\'s unlocks nothing');
+            node_assert_1.strict.equal(await client.call('secrets.lock', { ref, ttlMs: 30_000 }), null);
+            node_assert_1.strict.equal(await client.call('secrets.unlock', { ref, token: held.token }), null);
+            const again = await client.read('secrets.lock', { ref, ttlMs: 30_000 }, slots_1.SecretsLockAnswer);
+            node_assert_1.strict.ok(again !== null && again.token !== held.token, 'an unlocked credential is locked afresh, under a new token');
+            await client.call('secrets.unlock', { ref, token: again.token });
+        },
+    },
+    {
+        name: 'secrets: a lease whose ttl has lapsed is free, without an unlock',
+        async run(client) {
+            const ref = NEW_REF();
+            node_assert_1.strict.ok((await client.read('secrets.lock', { ref, ttlMs: 150 }, slots_1.SecretsLockAnswer)) !== null);
+            node_assert_1.strict.equal(await client.call('secrets.lock', { ref, ttlMs: 150 }), null, 'held until its ttl');
+            await sleep(400);
+            const taken = await client.read('secrets.lock', { ref, ttlMs: 30_000 }, slots_1.SecretsLockAnswer);
+            node_assert_1.strict.ok(taken !== null, 'a lapsed lease is taken over');
+            await client.call('secrets.unlock', { ref, token: taken.token });
+        },
+    },
+    {
+        name: 'secrets: assertWritable of a module that changes its entries answers null',
+        async run(client) {
+            node_assert_1.strict.equal(await client.call('secrets.assertWritable', { ref: NEW_REF() }), null);
+        },
+    },
+    {
+        name: 'secrets: a request without its ref, a lock without its ttl and an entry without its binding are refused as bad_request',
+        async run(client) {
+            await refusedWith('bad_request', client.call('secrets.resolve', {}));
+            await refusedWith('bad_request', client.call('secrets.lock', { ref: NEW_REF() }));
+            await refusedWith('bad_request', client.call('secrets.create', { ref: NEW_REF(), external: 'acme_crm', fields: {} }));
+        },
+    },
+];
+/** What a module that keeps its credentials where lf cannot change them
+ *  answers: `client` reaches one. Entries are refused by name with a reason;
+ *  everything a refresh needs still works. */
+exports.secretsReadOnlySlotCases = [
+    ...['secrets.create', 'secrets.replace'].map((method) => ({
+        name: `secrets: a read-only module answers ${method} with read_only and its reason, and keeps nothing`,
+        async run(client) {
+            const ref = NEW_REF();
+            const answer = await client.read(method, { ref, external: 'acme_crm', binding: 'legacy', fields: { api_key: 'k1' } }, slots_1.SecretsEntryAnswer);
+            node_assert_1.strict.ok(answer !== null && answer.kind === 'read_only' && answer.reason.length > 0, `${method} answered ${JSON.stringify(answer)}`);
+            node_assert_1.strict.equal(await client.call('secrets.resolve', { ref }), null);
+            node_assert_1.strict.equal((await listed(client)).find((entry) => entry.ref === ref), undefined);
+        },
+    })),
+    {
+        name: 'secrets: a read-only module answers secrets.delete with read_only and its reason',
+        async run(client) {
+            const answer = await client.read('secrets.delete', { ref: NEW_REF() }, slots_1.SecretsEntryAnswer);
+            node_assert_1.strict.ok(answer !== null && answer.kind === 'read_only' && answer.reason.length > 0, `secrets.delete answered ${JSON.stringify(answer)}`);
+        },
+    },
+    {
+        name: 'secrets: a read-only module answers secrets.assertWritable with read_only and its reason',
+        async run(client) {
+            const answer = await client.read('secrets.assertWritable', { ref: NEW_REF() }, slots_1.SecretsEntryAnswer);
+            node_assert_1.strict.ok(answer !== null && answer.kind === 'read_only' && answer.reason.length > 0, `secrets.assertWritable answered ${JSON.stringify(answer)}`);
+        },
+    },
+    {
+        name: 'secrets: a read-only module still lists, resolves and leases',
+        async run(client) {
+            const ref = NEW_REF();
+            node_assert_1.strict.ok(Array.isArray(await client.call('secrets.list', {})));
+            node_assert_1.strict.equal(await client.call('secrets.resolve', { ref }), null);
+            const held = await client.read('secrets.lock', { ref, ttlMs: 30_000 }, slots_1.SecretsLockAnswer);
+            node_assert_1.strict.ok(held !== null);
+            node_assert_1.strict.equal(await client.call('secrets.unlock', { ref, token: held.token }), null);
+        },
+    },
+];
+// ── 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/secrets.d.ts

@@ -0,0 +1,14 @@
+import type { SecretFields, SecretRecord, SecretsBackend, WriteBackOutcome } from '../secrets/family';
+import { type SlotAddress } from './wire';
+export declare class SecretsSlotBackend implements SecretsBackend {
+    private readonly client;
+    constructor(address: SlotAddress, settings?: Record<string, string>);
+    resolve(ref: string): Promise<SecretRecord | null>;
+    writeBack(ref: string, fields: SecretFields, expectedVersion: string): Promise<WriteBackOutcome>;
+    /** The module's lease, asked for again until it is free, held for `body`. */
+    exclusive<T>(ref: string, body: (store: SecretsBackend) => Promise<T>): Promise<T>;
+    /** A write-back is not what `read_only` answers for: only a refusal fails here. */
+    assertWritable(ref: string): Promise<void>;
+    /** Store a new credential (a legacy entry bound to `external`). */
+    seed(ref: string, external: string, fields: SecretFields): Promise<void>;
+}

package/dist/module_wire/secrets.js

@@ -0,0 +1,52 @@
+"use strict";
+// A secrets module spoken to over the wire as the secrets family's store
+// (`SecretsBackend`, secrets/family.ts): how the family's contract cases
+// (movement-engine services/secrets/contract.ts) hold any module of the
+// secrets slot to the meaning every store has, whether the module is served
+// by lf (`lf --contract-secrets-slot`) or is a third party's.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretsSlotBackend = void 0;
+const slots_1 = require("@listen-fire/engine-contracts/slots");
+const wire_1 = require("./wire");
+const LOCK_POLL_MS = 20;
+const LEASE_TTL_MS = 30_000;
+const LOCK_WAIT_MS = 10_000;
+class SecretsSlotBackend {
+    client;
+    constructor(address, settings = {}) {
+        this.client = new wire_1.SlotClient(address, settings);
+    }
+    resolve(ref) {
+        return this.client.read('secrets.resolve', { ref }, slots_1.SecretsRecord.nullable());
+    }
+    async writeBack(ref, fields, expectedVersion) {
+        return this.client.read('secrets.writeBack', { ref, fields, expectedVersion }, slots_1.SecretsWriteBackAnswer);
+    }
+    /** The module's lease, asked for again until it is free, held for `body`. */
+    async exclusive(ref, body) {
+        const until = Date.now() + LOCK_WAIT_MS;
+        for (;;) {
+            const lease = await this.client.read('secrets.lock', { ref, ttlMs: LEASE_TTL_MS }, slots_1.SecretsLockAnswer);
+            if (lease !== null) {
+                try {
+                    return await body(this);
+                }
+                finally {
+                    await this.client.call('secrets.unlock', { ref, token: lease.token });
+                }
+            }
+            if (Date.now() > until)
+                throw new Error(`the secrets module kept credential "${ref}" locked for ${LOCK_WAIT_MS / 1000}s`);
+            await new Promise((done) => setTimeout(done, LOCK_POLL_MS));
+        }
+    }
+    /** A write-back is not what `read_only` answers for: only a refusal fails here. */
+    async assertWritable(ref) {
+        await this.client.call('secrets.assertWritable', { ref });
+    }
+    /** Store a new credential (a legacy entry bound to `external`). */
+    async seed(ref, external, fields) {
+        await this.client.call('secrets.create', { ref, external, binding: 'legacy', fields });
+    }
+}
+exports.SecretsSlotBackend = SecretsSlotBackend;

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

@@ -0,0 +1,26 @@
+/**
+ * How long the vendor asked a rate-limited caller to wait, or undefined when
+ * it did not say. Read from `e.headers` (a plain object or `Headers`; a
+ * `Response` is one) or `e.response.headers`, else Google's `RetryInfo` in an
+ * error's message. Clamped to [1s, 120s] so a hostile or absurd value can
+ * 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

@@ -0,0 +1,119 @@
+"use strict";
+// How long a rate-limited vendor asked its caller to wait. Here, below both
+// the engine and the module kit, so the kit's limits door and the engine's
+// 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;
+function clamp(ms) {
+    return Math.min(MAX_WAIT_MS, Math.max(MIN_WAIT_MS, Math.round(ms)));
+}
+/** `Retry-After` is either whole seconds or an HTTP date. */
+function fromHeaderValue(value, now) {
+    const trimmed = value.trim();
+    if (/^\d+(\.\d+)?$/.test(trimmed))
+        return Number(trimmed) * SECOND;
+    const date = Date.parse(trimmed);
+    return Number.isNaN(date) ? undefined : date - now;
+}
+function readHeader(headers, name) {
+    if (!headers || typeof headers !== 'object')
+        return undefined;
+    if ('get' in headers && typeof headers.get === 'function') {
+        const value = headers.get(name);
+        return typeof value === 'string' ? value : undefined;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name && typeof value === 'string')
+            return value;
+    }
+    return undefined;
+}
+function field(value, name) {
+    return typeof value === 'object' && value !== null ? Reflect.get(value, name) : undefined;
+}
+/**
+ * Google's `google.rpc.RetryInfo` detail: `"retryDelay": "17s"` (or
+ * `"17.5s"`) on the wire, `{ seconds: 17 }` in a decoded form. The genai SDK's
+ * `ApiError` carries the JSON body only as text in its message.
+ */
+function fromRetryInfo(text) {
+    const quoted = /"retryDelay"\s*:\s*"(\d+(?:\.\d+)?)s"/.exec(text);
+    if (quoted)
+        return Number(quoted[1]) * SECOND;
+    const object = /"retryDelay"\s*:\s*\{\s*"seconds"\s*:\s*"?(\d+)"?/.exec(text);
+    return object ? Number(object[1]) * SECOND : undefined;
+}
+/**
+ * How long the vendor asked a rate-limited caller to wait, or undefined when
+ * it did not say. Read from `e.headers` (a plain object or `Headers`; a
+ * `Response` is one) or `e.response.headers`, else Google's `RetryInfo` in an
+ * error's message. Clamped to [1s, 120s] so a hostile or absurd value can
+ * neither spin nor stall a caller.
+ */
+function vendorWaitMs(e, now = Date.now()) {
+    const header = readHeader(field(e, 'headers'), 'retry-after') ?? readHeader(field(field(e, 'response'), 'headers'), 'retry-after');
+    const fromHeader = header === undefined ? undefined : fromHeaderValue(header, now);
+    if (fromHeader !== undefined)
+        return clamp(fromHeader);
+    const text = e instanceof Error ? e.message : undefined;
+    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.7",
+  "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.7"
+    "@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"