@listen-fire/engine-contracts 0.12.1 → 0.12.2

package/dist/slots/movements.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-export declare const MOVEMENTS_METHODS: readonly ["movements.list", "movements.read", "movements.write"];
+export declare const MOVEMENTS_METHODS: readonly ["movements.list", "movements.read", "movements.write", "movements.watch"];
 /** A file's path under the movements folder: `/`-separated, ending `.mvt`,
  *  no segment empty, `.` or `..`, and no `\` (`orders/sync.mvt`). */
 export declare const MovementPath: z.ZodString;
@@ -39,3 +39,39 @@ export declare const MovementsWriteAnswer: z.ZodDiscriminatedUnion<[z.ZodObject<
     reason: z.ZodString;
 }, z.core.$strip>], "kind">;
 export type MovementsWriteAnswerShape = z.infer<typeof MovementsWriteAnswer>;
+/** One change `movements.watch` reports. `version` is the one `read` answers; a module that can change its files gives it on `added` and `changed`. */
+export declare const MovementsChange: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"added">;
+    path: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"changed">;
+    path: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"removed">;
+    path: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type MovementsChangeShape = z.infer<typeof MovementsChange>;
+export declare const MovementsWatchRequest: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    waitMs: z.ZodNumber;
+}, z.core.$strip>;
+export declare const MovementsWatchAnswer: z.ZodUnion<readonly [z.ZodObject<{
+    cursor: z.ZodString;
+    events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"added">;
+        path: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"changed">;
+        path: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"removed">;
+        path: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>, z.ZodObject<{
+    resync: z.ZodLiteral<true>;
+}, z.core.$strip>]>;
+export type MovementsWatchAnswerShape = z.infer<typeof MovementsWatchAnswer>;

package/dist/slots/movements.js

@@ -4,10 +4,11 @@
 // the movements folder, reads one, and writes one by compare-and-swap on its
 // version. `lf.yaml` and the externals folder stay local files.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MovementsWriteAnswer = exports.MovementsWriteRequest = exports.MovementsReadRequest = exports.MovementsReadAnswer = exports.MovementsListAnswer = exports.MovementsListed = exports.MovementPath = exports.MOVEMENTS_METHODS = void 0;
+exports.MovementsWatchAnswer = exports.MovementsWatchRequest = exports.MovementsChange = exports.MovementsWriteAnswer = exports.MovementsWriteRequest = exports.MovementsReadRequest = exports.MovementsReadAnswer = exports.MovementsListAnswer = exports.MovementsListed = exports.MovementPath = exports.MOVEMENTS_METHODS = void 0;
 exports.isMovementPath = isMovementPath;
 const zod_1 = require("zod");
-exports.MOVEMENTS_METHODS = ['movements.list', 'movements.read', 'movements.write'];
+const wire_1 = require("./wire");
+exports.MOVEMENTS_METHODS = ['movements.list', 'movements.read', 'movements.write', 'movements.watch'];
 /** A file's path under the movements folder: `/`-separated, ending `.mvt`,
  *  no segment empty, `.` or `..`, and no `\` (`orders/sync.mvt`). */
 exports.MovementPath = zod_1.z.string().refine(isMovementPath, 'a movement path: relative to the movements folder, `/`-separated, ending .mvt');
@@ -36,3 +37,11 @@ exports.MovementsWriteAnswer = zod_1.z.discriminatedUnion('kind', [
     /** The module keeps the project's movements where `lf` cannot change them. */
     zod_1.z.object({ kind: zod_1.z.literal('read_only'), reason: zod_1.z.string().min(1) }),
 ]);
+/** One change `movements.watch` reports. `version` is the one `read` answers; a module that can change its files gives it on `added` and `changed`. */
+exports.MovementsChange = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z.object({ kind: zod_1.z.literal('added'), path: exports.MovementPath, version: Version.optional() }),
+    zod_1.z.object({ kind: zod_1.z.literal('changed'), path: exports.MovementPath, version: Version.optional() }),
+    zod_1.z.object({ kind: zod_1.z.literal('removed'), path: exports.MovementPath }),
+]);
+exports.MovementsWatchRequest = wire_1.WatchRequest;
+exports.MovementsWatchAnswer = (0, wire_1.watchAnswer)(exports.MovementsChange);

package/dist/slots/wire.d.ts

@@ -47,3 +47,33 @@ export declare const WireSlotManifest: z.ZodObject<{
 export type WireSlotManifestShape = z.infer<typeof WireSlotManifest>;
 /** The error code a store answers when a fenced write finds the run's lease gone. */
 export declare const RUN_LEASE_LOST_CODE = "run_lease_lost";
+/** The most a module must hold a `<slot>.watch` request: lf asks for at most
+ *  this, and a module honours at most this whatever `waitMs` says. */
+export declare const WATCH_WAIT_CAP_MS = 30000;
+/**
+ * The generic change feed any slot may adopt (`<slot>.watch`, the adapter
+ * protocol's "Watching for changes"). The caller holds a cursor and asks for
+ * what happened after it; the module holds the request up to `waitMs`, then
+ * answers.
+ *
+ * - An absent cursor answers the module's current cursor and no events.
+ * - `waitMs` is a non-negative integer; a module honours at most
+ *   `WATCH_WAIT_CAP_MS` and may answer sooner, at once with `events: []`.
+ * - A cursor the module never gave, or can no longer serve, answers
+ *   `{ resync: true }`: the caller lists afresh and asks without a cursor.
+ * - Events from one cursor are in order, and a cursor a module has answered is
+ *   never answered again with fewer events.
+ * - Cursors are positions in the module's log, not per caller: every caller
+ *   holding a cursor sees every event after it.
+ */
+export declare const WatchRequest: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    waitMs: z.ZodNumber;
+}, z.core.$strip>;
+export type WatchRequestShape = z.infer<typeof WatchRequest>;
+export declare function watchAnswer<E extends z.ZodType>(event: E): z.ZodUnion<readonly [z.ZodObject<{
+    cursor: z.ZodString;
+    events: z.ZodArray<E>;
+}, z.core.$strip>, z.ZodObject<{
+    resync: z.ZodLiteral<true>;
+}, z.core.$strip>]>;

package/dist/slots/wire.js

@@ -13,7 +13,8 @@
 // The shapes only: a Node client, server and starter are module-runtime's
 // `module-wire`.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RUN_LEASE_LOST_CODE = exports.WireSlotManifest = exports.SlotAnswerEnvelope = exports.SlotError = exports.SlotRequestEnvelope = void 0;
+exports.WatchRequest = exports.WATCH_WAIT_CAP_MS = exports.RUN_LEASE_LOST_CODE = exports.WireSlotManifest = exports.SlotAnswerEnvelope = exports.SlotError = exports.SlotRequestEnvelope = void 0;
+exports.watchAnswer = watchAnswer;
 const zod_1 = require("zod");
 const protocol_1 = require("../protocol");
 exports.SlotRequestEnvelope = zod_1.z.object({
@@ -44,3 +45,26 @@ exports.WireSlotManifest = zod_1.z.object({
 });
 /** The error code a store answers when a fenced write finds the run's lease gone. */
 exports.RUN_LEASE_LOST_CODE = 'run_lease_lost';
+/** The most a module must hold a `<slot>.watch` request: lf asks for at most
+ *  this, and a module honours at most this whatever `waitMs` says. */
+exports.WATCH_WAIT_CAP_MS = 30_000;
+/**
+ * The generic change feed any slot may adopt (`<slot>.watch`, the adapter
+ * protocol's "Watching for changes"). The caller holds a cursor and asks for
+ * what happened after it; the module holds the request up to `waitMs`, then
+ * answers.
+ *
+ * - An absent cursor answers the module's current cursor and no events.
+ * - `waitMs` is a non-negative integer; a module honours at most
+ *   `WATCH_WAIT_CAP_MS` and may answer sooner, at once with `events: []`.
+ * - A cursor the module never gave, or can no longer serve, answers
+ *   `{ resync: true }`: the caller lists afresh and asks without a cursor.
+ * - Events from one cursor are in order, and a cursor a module has answered is
+ *   never answered again with fewer events.
+ * - Cursors are positions in the module's log, not per caller: every caller
+ *   holding a cursor sees every event after it.
+ */
+exports.WatchRequest = zod_1.z.object({ cursor: zod_1.z.string().min(1).optional(), waitMs: zod_1.z.number().int().min(0) });
+function watchAnswer(event) {
+    return zod_1.z.union([zod_1.z.object({ cursor: zod_1.z.string().min(1), events: zod_1.z.array(event) }), zod_1.z.object({ resync: zod_1.z.literal(true) })]);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@listen-fire/engine-contracts",
   "license": "Apache-2.0",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "The contracts the movement engine speaks: the tenant id, the host families and entry-point inputs, the parked state, file descriptors, the adapter protocol, the adapter contract and its manifest, the catalog's schema types and positions, the Expression vocabulary, plugins as data and the model names. Runtime-neutral: no Node import, no ambient types.",
   "engines": {
     "node": ">=22.23.4 <23"
@@ -30,7 +30,7 @@
   "type": "commonjs",
   "dependencies": {
     "zod": "4.1.12",
-    "@listen-fire/movement-lang": "^0.12.1"
+    "@listen-fire/movement-lang": "^0.12.2"
   },
   "devDependencies": {
     "@types/node": "20.16.5",