@listen-fire/module-runtime 0.12.1 → 0.12.3

package/dist/module_wire/conformance.d.ts

@@ -46,6 +46,13 @@ export declare const secretsReadOnlySlotCases: SlotConformanceCase[];
  *  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[];
+/** A removed file is reported `removed`. The wire has no delete, so the
+ *  harness supplies the removal (the test module's `remove`, a file deleted
+ *  from the folder). */
+export declare const movementsWatchRemovalCase: (remove: (path: string) => Promise<void>) => SlotConformanceCase;
+/** A module honours at most the cap: with nothing changing, a request for a
+ *  minute is answered within the cap (plus slack). It takes about 30 s. */
+export declare const movementsWatchCapCase: 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. */

package/dist/module_wire/conformance.js

@@ -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.movementsReadOnlySlotCases = exports.movementsSlotCases = exports.secretsReadOnlySlotCases = exports.secretsSlotCases = exports.wakeSlotCases = exports.ocrSlotCases = exports.filesSlotCases = exports.judgeSlotCases = exports.modelsSlotCases = void 0;
+exports.movementsReadOnlySlotCases = exports.movementsWatchCapCase = exports.movementsWatchRemovalCase = 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");
@@ -463,6 +463,40 @@ async function createdMovement(client, path, text) {
     node_assert_1.strict.equal(made.kind, 'written', `creating ${path} answered ${JSON.stringify(made)}`);
     return made.kind === 'written' ? made.version : '';
 }
+const watchMovements = (client, params) => client.read('movements.watch', params, slots_1.MovementsWatchAnswer);
+/** The module's current cursor (a watch without one answers it, no events). */
+async function currentCursor(client) {
+    const answer = await watchMovements(client, { waitMs: 0 });
+    node_assert_1.strict.ok('cursor' in answer, `a watch without a cursor answered ${JSON.stringify(answer)}`);
+    return 'cursor' in answer ? answer.cursor : '';
+}
+const WATCH_DEADLINE_MS = 10_000;
+/** Re-asks from `cursor` until an event satisfies `wanted` or the deadline
+ *  passes, so a module that answers at once (and one that holds) both pass.
+ *  Returns the cursor after the answer that carried it and every event seen. */
+async function watchedUntil(client, cursor, wanted) {
+    const deadline = Date.now() + WATCH_DEADLINE_MS;
+    const seen = [];
+    let from = cursor;
+    while (Date.now() < deadline) {
+        const asked = Date.now();
+        const answer = await watchMovements(client, { cursor: from, waitMs: 1_000 });
+        node_assert_1.strict.ok('cursor' in answer, `a watch from a cursor the module gave answered ${JSON.stringify(answer)}`);
+        if (!('cursor' in answer))
+            break;
+        from = answer.cursor;
+        seen.push(...answer.events);
+        if (answer.events.some(wanted))
+            return { cursor: from, seen };
+        if (Date.now() - asked < 500)
+            await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    node_assert_1.strict.fail(`no wanted event within ${WATCH_DEADLINE_MS} ms; saw ${JSON.stringify(seen)}`);
+}
+const eventAt = (path, kind) => (event) => event.path === path && event.kind === kind;
+async function readVersion(client, path) {
+    return (await client.read('movements.read', { path }, slots_1.MovementsReadAnswer))?.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. */
@@ -554,7 +588,98 @@ exports.movementsSlotCases = [
             node_assert_1.strict.equal(await client.call('movements.read', { path }), null);
         },
     },
+    {
+        name: 'movements: a watch without a cursor answers a cursor and no events',
+        async run(client) {
+            const answer = await watchMovements(client, { waitMs: 0 });
+            node_assert_1.strict.ok('cursor' in answer && answer.events.length === 0, `answered ${JSON.stringify(answer)}`);
+        },
+    },
+    {
+        name: 'movements: a file created after a watch is reported added with the version read answers; a replace is changed with the new version',
+        async run(client) {
+            const cursor = await currentCursor(client);
+            const path = NEW_MOVEMENT();
+            const first = await createdMovement(client, path, 'one');
+            const added = await watchedUntil(client, cursor, eventAt(path, 'added'));
+            const event = added.seen.find(eventAt(path, 'added'));
+            node_assert_1.strict.equal(event && event.kind !== 'removed' ? event.version : undefined, first, 'added carries the version read answers');
+            const replaced = await writeMovement(client, path, 'two', first);
+            node_assert_1.strict.equal(replaced.kind, 'written');
+            const changed = await watchedUntil(client, added.cursor, eventAt(path, 'changed'));
+            const edit = changed.seen.find(eventAt(path, 'changed'));
+            node_assert_1.strict.equal(edit && edit.kind !== 'removed' ? edit.version : undefined, await readVersion(client, path), 'changed carries the new version');
+        },
+    },
+    {
+        name: 'movements: an event answered once is not answered again from the next cursor, and a write between two calls appears in the second',
+        async run(client) {
+            const first = NEW_MOVEMENT();
+            await createdMovement(client, first, 'one');
+            const cursor = await currentCursor(client);
+            const second = NEW_MOVEMENT();
+            await createdMovement(client, second, 'two');
+            const afterSecond = await watchedUntil(client, cursor, eventAt(second, 'added'));
+            node_assert_1.strict.equal(afterSecond.seen.filter(eventAt(first, 'added')).length, 0, 'a file written before the cursor is not an event after it');
+            const third = NEW_MOVEMENT();
+            await createdMovement(client, third, 'three');
+            const afterThird = await watchedUntil(client, afterSecond.cursor, eventAt(third, 'added'));
+            node_assert_1.strict.equal(afterThird.seen.filter(eventAt(second, 'added')).length, 0, 'an answered event is not answered again');
+        },
+    },
+    {
+        name: 'movements: two watchers from one cursor both see the change',
+        async run(client) {
+            const cursor = await currentCursor(client);
+            const path = NEW_MOVEMENT();
+            await createdMovement(client, path, 'one');
+            await watchedUntil(client, cursor, eventAt(path, 'added'));
+            await watchedUntil(client, cursor, eventAt(path, 'added'));
+        },
+    },
+    {
+        name: 'movements: a cursor the module never gave answers resync',
+        async run(client) {
+            node_assert_1.strict.deepEqual(await watchMovements(client, { cursor: 'conformance-unknown', waitMs: 0 }), { resync: true });
+        },
+    },
+    {
+        name: 'movements: a watch without waitMs, with a negative waitMs or with a cursor that is not a string is refused as bad_request',
+        async run(client) {
+            await refusedWith('bad_request', client.call('movements.watch', {}));
+            await refusedWith('bad_request', client.call('movements.watch', { cursor: 'x' }));
+            await refusedWith('bad_request', client.call('movements.watch', { waitMs: -1 }));
+            await refusedWith('bad_request', client.call('movements.watch', { waitMs: 0, cursor: 5 }));
+        },
+    },
 ];
+/** A removed file is reported `removed`. The wire has no delete, so the
+ *  harness supplies the removal (the test module's `remove`, a file deleted
+ *  from the folder). */
+const movementsWatchRemovalCase = (remove) => ({
+    name: 'movements: a removed file is reported removed',
+    async run(client) {
+        const path = NEW_MOVEMENT();
+        await createdMovement(client, path, 'one');
+        const cursor = await currentCursor(client);
+        await remove(path);
+        await watchedUntil(client, cursor, eventAt(path, 'removed'));
+    },
+});
+exports.movementsWatchRemovalCase = movementsWatchRemovalCase;
+/** A module honours at most the cap: with nothing changing, a request for a
+ *  minute is answered within the cap (plus slack). It takes about 30 s. */
+exports.movementsWatchCapCase = {
+    name: 'movements: a watch for longer than the cap is answered within the cap',
+    async run(client) {
+        const cursor = await currentCursor(client);
+        const asked = Date.now();
+        const answer = await watchMovements(client, { cursor, waitMs: 60_000 });
+        node_assert_1.strict.ok(!('resync' in answer), 'a cursor the module gave is not resync');
+        const took = Date.now() - asked;
+        node_assert_1.strict.ok(took < slots_1.WATCH_WAIT_CAP_MS + 2_000, `a watch for 60000 ms took ${took} ms`);
+    },
+};
 /** 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. */
@@ -576,4 +701,11 @@ exports.movementsReadOnlySlotCases = [
             node_assert_1.strict.equal(await client.call('movements.read', { path: NEW_MOVEMENT() }), null);
         },
     },
+    {
+        name: 'movements: a read-only module still watches: a cursor without one, resync on one it never gave',
+        async run(client) {
+            await currentCursor(client);
+            node_assert_1.strict.deepEqual(await watchMovements(client, { cursor: 'conformance-unknown', waitMs: 0 }), { resync: true });
+        },
+    },
 ];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@listen-fire/module-runtime",
   "license": "Apache-2.0",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "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.23.4 <23"
@@ -22,7 +22,7 @@
   "type": "commonjs",
   "dependencies": {
     "zod": "4.1.12",
-    "@listen-fire/engine-contracts": "^0.12.1"
+    "@listen-fire/engine-contracts": "^0.12.3"
   },
   "devDependencies": {
     "@types/node": "20.16.5",