@listen-fire/engine-contracts 0.12.0-rc.8 → 0.12.1

package/dist/protocol.d.ts

@@ -1423,6 +1423,9 @@ export declare const WireSignedInboundDeclaration: z.ZodObject<{
         installer: "installer";
         provider: "provider";
     }>>;
+    deliveryId: z.ZodOptional<z.ZodObject<{
+        header: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
  * The module checks its own inbound requests (`scheme: module`): the host
@@ -1457,6 +1460,9 @@ export declare const WireInboundDeclaration: z.ZodDiscriminatedUnion<[z.ZodObjec
         installer: "installer";
         provider: "provider";
     }>>;
+    deliveryId: z.ZodOptional<z.ZodObject<{
+        header: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     providerKey: z.ZodString;
     scheme: z.ZodLiteral<"module">;
@@ -1551,8 +1557,10 @@ export type WireModuleKindShape = z.infer<typeof WireModuleKind>;
  *  (a scanned file is refused, saying the slot is empty). `secrets` is
  *  where credentials are kept (`lf`'s default: its secrets file); a secrets
  *  module's own settings come from the environment or that file, never
- *  from itself. */
-export declare const CORE_SLOTS: readonly ["models", "judge", "store", "files", "limiter", "loopGuard", "browser", "wake", "ocr", "secrets"];
+ *  from itself. `movements` answers the project's movement files by name
+ *  (`lf`'s default: the movements folder); its module's own settings come
+ *  from the same two places. */
+export declare const CORE_SLOTS: readonly ["models", "judge", "store", "files", "limiter", "loopGuard", "browser", "wake", "ocr", "secrets", "movements"];
 export declare const WireCoreSlot: z.ZodEnum<{
     store: "store";
     models: "models";
@@ -1564,6 +1572,7 @@ export declare const WireCoreSlot: z.ZodEnum<{
     wake: "wake";
     ocr: "ocr";
     secrets: "secrets";
+    movements: "movements";
 }>;
 export type WireCoreSlotShape = z.infer<typeof WireCoreSlot>;
 /** One construction argument the install supplies (an Airtable `base`, a
@@ -1623,6 +1632,7 @@ export declare const WireModuleDeclarations: z.ZodObject<{
         wake: "wake";
         ocr: "ocr";
         secrets: "secrets";
+        movements: "movements";
     }>>;
     settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -1681,6 +1691,9 @@ export declare const WireModuleDeclarations: z.ZodObject<{
             installer: "installer";
             provider: "provider";
         }>>;
+        deliveryId: z.ZodOptional<z.ZodObject<{
+            header: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>, z.ZodObject<{
         providerKey: z.ZodString;
         scheme: z.ZodLiteral<"module">;
@@ -1765,6 +1778,7 @@ export declare const WireManifestResult: z.ZodObject<{
         wake: "wake";
         ocr: "ocr";
         secrets: "secrets";
+        movements: "movements";
     }>>;
     settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -1823,6 +1837,9 @@ export declare const WireManifestResult: z.ZodObject<{
             installer: "installer";
             provider: "provider";
         }>>;
+        deliveryId: z.ZodOptional<z.ZodObject<{
+            header: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>, z.ZodObject<{
         providerKey: z.ZodString;
         scheme: z.ZodLiteral<"module">;
@@ -2070,6 +2087,7 @@ export declare const WireInboundCheck: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>>;
     wakeKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
     checkpoint: z.ZodOptional<z.ZodUnknown>;
+    deliveryId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     outcome: z.ZodLiteral<"refused">;
     status: z.ZodOptional<z.ZodNumber>;
@@ -2098,6 +2116,7 @@ export declare const HostModelRequest: z.ZodObject<{
     schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     toolName: z.ZodOptional<z.ZodString>;
     toolDescription: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type HostModelRequestShape = z.infer<typeof HostModelRequest>;
 /** The tokens a model call spent: what a run's usage reports, beside its cost. */
@@ -2267,6 +2286,7 @@ export declare const METHODS: {
                 wake: "wake";
                 ocr: "ocr";
                 secrets: "secrets";
+                movements: "movements";
             }>>;
             settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -2325,6 +2345,9 @@ export declare const METHODS: {
                     installer: "installer";
                     provider: "provider";
                 }>>;
+                deliveryId: z.ZodOptional<z.ZodObject<{
+                    header: z.ZodString;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerKey: z.ZodString;
                 scheme: z.ZodLiteral<"module">;
@@ -3782,6 +3805,7 @@ export declare const METHODS: {
             }, z.core.$strip>>;
             wakeKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
             checkpoint: z.ZodOptional<z.ZodUnknown>;
+            deliveryId: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodObject<{
             outcome: z.ZodLiteral<"refused">;
             status: z.ZodOptional<z.ZodNumber>;

package/dist/protocol.js

@@ -664,6 +664,10 @@ exports.WireSignedInboundDeclaration = zod_1.z.object({
         .min(1),
     intercepts: zod_1.z.array(exports.WireInboundIntercept).optional(),
     secretIssuedBy: WireSecretIssuedBy.optional(),
+    /** The header carrying the provider's id for each delivery (GitHub's
+     *  `x-github-delivery`), read by the host before the module sees the body:
+     *  a redelivery under an id the host kept before is acked and runs nothing. */
+    deliveryId: zod_1.z.object({ header: zod_1.z.string().regex(HEADER_NAME, 'a delivery id header is a lower-case header name') }).optional(),
 });
 /**
  * The module checks its own inbound requests (`scheme: module`): the host
@@ -741,8 +745,10 @@ exports.WireModuleKind = zod_1.z.enum(exports.MODULE_KINDS);
  *  (a scanned file is refused, saying the slot is empty). `secrets` is
  *  where credentials are kept (`lf`'s default: its secrets file); a secrets
  *  module's own settings come from the environment or that file, never
- *  from itself. */
-exports.CORE_SLOTS = ['models', 'judge', 'store', 'files', 'limiter', 'loopGuard', 'browser', 'wake', 'ocr', 'secrets'];
+ *  from itself. `movements` answers the project's movement files by name
+ *  (`lf`'s default: the movements folder); its module's own settings come
+ *  from the same two places. */
+exports.CORE_SLOTS = ['models', 'judge', 'store', 'files', 'limiter', 'loopGuard', 'browser', 'wake', 'ocr', 'secrets', 'movements'];
 exports.WireCoreSlot = zod_1.z.enum(exports.CORE_SLOTS);
 /** One construction argument the install supplies (an Airtable `base`, a
  *  Sheets `spreadsheet`): asked for when the module is set up (`lf connect`,
@@ -929,6 +935,9 @@ exports.WireInboundCheck = zod_1.z.discriminatedUnion('outcome', [
         events: zod_1.z.array(exports.WireDiscriminableEvent),
         wakeKeys: zod_1.z.array(zod_1.z.string().min(1)).optional(),
         checkpoint: zod_1.z.unknown().optional(),
+        /** The provider's id for this delivery: a redelivery under an id the
+         *  host kept before is acked and runs nothing. */
+        deliveryId: zod_1.z.string().min(1).optional(),
     }),
     zod_1.z.object({
         outcome: zod_1.z.literal('refused'),
@@ -956,6 +965,8 @@ exports.HostModelRequest = zod_1.z.object({
     schema: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
     toolName: zod_1.z.string().optional(),
     toolDescription: zod_1.z.string().optional(),
+    /** The run the call is made for, when it is made inside one: a host's usage rows attribute the call to it. */
+    runId: zod_1.z.string().optional(),
 });
 /** The tokens a model call spent: what a run's usage reports, beside its cost. */
 exports.WireModelUsage = zod_1.z.object({

package/dist/slots/index.d.ts

@@ -6,3 +6,4 @@ export * from './browser';
 export * from './wake';
 export * from './ocr';
 export * from './secrets';
+export * from './movements';

package/dist/slots/index.js

@@ -25,3 +25,4 @@ __exportStar(require("./browser"), exports);
 __exportStar(require("./wake"), exports);
 __exportStar(require("./ocr"), exports);
 __exportStar(require("./secrets"), exports);
+__exportStar(require("./movements"), exports);

package/dist/slots/models.d.ts

@@ -10,6 +10,7 @@ export declare const ModelsCallRequest: z.ZodObject<{
     schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     toolName: z.ZodOptional<z.ZodString>;
     toolDescription: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
     effort: z.ZodOptional<z.ZodEnum<{
         low: "low";
         medium: "medium";

package/dist/slots/movements.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+export declare const MOVEMENTS_METHODS: readonly ["movements.list", "movements.read", "movements.write"];
+/** 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;
+export declare function isMovementPath(path: string): boolean;
+/** One file `movements.list` names; without a version, `lf` reads it on every scan. */
+export declare const MovementsListed: z.ZodObject<{
+    path: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const MovementsListAnswer: z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+/** What `movements.read` answers (or null: nothing is at the path). */
+export declare const MovementsReadAnswer: z.ZodNullable<z.ZodObject<{
+    text: z.ZodString;
+    version: z.ZodString;
+}, z.core.$strip>>;
+export declare const MovementsReadRequest: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strip>;
+/** `expectedVersion` is present: a version replaces the file only if it is
+ *  still at it; null creates it only if nothing is at the path. */
+export declare const MovementsWriteRequest: z.ZodObject<{
+    path: z.ZodString;
+    text: z.ZodString;
+    expectedVersion: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const MovementsWriteAnswer: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"written">;
+    version: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"conflict">;
+    current: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"read_only">;
+    reason: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type MovementsWriteAnswerShape = z.infer<typeof MovementsWriteAnswer>;

package/dist/slots/movements.js

@@ -0,0 +1,38 @@
+"use strict";
+// The movements slot's methods (docs/contracts/movements-slot.md): where the
+// project's movement files live. A module lists every file by its path under
+// 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.isMovementPath = isMovementPath;
+const zod_1 = require("zod");
+exports.MOVEMENTS_METHODS = ['movements.list', 'movements.read', 'movements.write'];
+/** 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');
+function isMovementPath(path) {
+    const segments = path.split('/');
+    return (!path.includes('\\') &&
+        path.endsWith('.mvt') &&
+        segments.every((segment) => segment !== '' && segment !== '.' && segment !== '..') &&
+        segments.at(-1) !== '.mvt');
+}
+/** Opaque; it changes whenever the text changes. */
+const Version = zod_1.z.string().min(1);
+/** One file `movements.list` names; without a version, `lf` reads it on every scan. */
+exports.MovementsListed = zod_1.z.object({ path: exports.MovementPath, version: Version.optional() });
+exports.MovementsListAnswer = zod_1.z.array(exports.MovementsListed);
+/** What `movements.read` answers (or null: nothing is at the path). */
+exports.MovementsReadAnswer = zod_1.z.object({ text: zod_1.z.string(), version: Version }).nullable();
+exports.MovementsReadRequest = zod_1.z.object({ path: exports.MovementPath });
+/** `expectedVersion` is present: a version replaces the file only if it is
+ *  still at it; null creates it only if nothing is at the path. */
+exports.MovementsWriteRequest = zod_1.z.object({ path: exports.MovementPath, text: zod_1.z.string(), expectedVersion: Version.nullable() });
+exports.MovementsWriteAnswer = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z.object({ kind: zod_1.z.literal('written'), version: Version }),
+    /** `current`: the version there now, or null when there is none. */
+    zod_1.z.object({ kind: zod_1.z.literal('conflict'), current: Version.nullable() }),
+    /** 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) }),
+]);

package/dist/slots/wire.d.ts

@@ -40,6 +40,7 @@ export declare const WireSlotManifest: z.ZodObject<{
         wake: "wake";
         ocr: "ocr";
         secrets: "secrets";
+        movements: "movements";
     }>;
     methods: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;

package/dist/versions.d.ts

@@ -1,5 +1,6 @@
-import { CATALOG_SNAPSHOT_VERSION, DEPRECATED_CATALOG_SNAPSHOT_VERSIONS, SUPPORTED_CATALOG_SNAPSHOT_VERSIONS } from '@listen-fire/movement-lang';
+import { CATALOG_SNAPSHOT_VERSION, DEPRECATED_CATALOG_SNAPSHOT_VERSIONS, STORY_ANALYSIS_VERSION, SUPPORTED_CATALOG_SNAPSHOT_VERSIONS, SUPPORTED_STORY_ANALYSIS_VERSIONS } from '@listen-fire/movement-lang';
 export { CATALOG_SNAPSHOT_VERSION, DEPRECATED_CATALOG_SNAPSHOT_VERSIONS, SUPPORTED_CATALOG_SNAPSHOT_VERSIONS };
+export { STORY_ANALYSIS_VERSION, SUPPORTED_STORY_ANALYSIS_VERSIONS };
 /** A parked flow's state (docs/contracts/park-state.md). Engine to engine: a
  *  host stores it and hands it back. Version 2 is the Rust engine's; the earlier
  *  TypeScript engine wrote and read 1. */
@@ -47,6 +48,11 @@ export declare const CONTRACTS: {
         readonly supported: readonly [1];
         readonly deprecated: readonly [];
     };
+    readonly 'story-analysis': {
+        readonly current: 1;
+        readonly supported: readonly number[];
+        readonly deprecated: readonly [];
+    };
 };
 /** The language's contract (docs/contracts/language-versions.md) is not an
  *  integer of its own: it is the release's version, and a release reads the

package/dist/versions.js

@@ -8,13 +8,15 @@
 // the version at the point of difference, never by a forked reader. A version
 // this release does not support is refused at the boundary, loudly.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LANGUAGE_CONTRACT = exports.CONTRACTS = exports.SYSTEM_CALLER_VERSION = exports.SUPPORTED_HOST_FAMILIES_VERSIONS = exports.HOST_FAMILIES_VERSION = exports.SUPPORTED_PARK_STATE_VERSIONS = exports.PARK_STATE_VERSION = exports.SUPPORTED_CATALOG_SNAPSHOT_VERSIONS = exports.DEPRECATED_CATALOG_SNAPSHOT_VERSIONS = exports.CATALOG_SNAPSHOT_VERSION = void 0;
+exports.LANGUAGE_CONTRACT = exports.CONTRACTS = exports.SYSTEM_CALLER_VERSION = exports.SUPPORTED_HOST_FAMILIES_VERSIONS = exports.HOST_FAMILIES_VERSION = exports.SUPPORTED_PARK_STATE_VERSIONS = exports.PARK_STATE_VERSION = exports.SUPPORTED_STORY_ANALYSIS_VERSIONS = exports.STORY_ANALYSIS_VERSION = exports.SUPPORTED_CATALOG_SNAPSHOT_VERSIONS = exports.DEPRECATED_CATALOG_SNAPSHOT_VERSIONS = exports.CATALOG_SNAPSHOT_VERSION = void 0;
 exports.refuseUnsupportedHostFamiliesVersion = refuseUnsupportedHostFamiliesVersion;
 exports.refuseUnsupportedParkStateVersion = refuseUnsupportedParkStateVersion;
 const movement_lang_1 = require("@listen-fire/movement-lang");
 Object.defineProperty(exports, "CATALOG_SNAPSHOT_VERSION", { enumerable: true, get: function () { return movement_lang_1.CATALOG_SNAPSHOT_VERSION; } });
 Object.defineProperty(exports, "DEPRECATED_CATALOG_SNAPSHOT_VERSIONS", { enumerable: true, get: function () { return movement_lang_1.DEPRECATED_CATALOG_SNAPSHOT_VERSIONS; } });
+Object.defineProperty(exports, "STORY_ANALYSIS_VERSION", { enumerable: true, get: function () { return movement_lang_1.STORY_ANALYSIS_VERSION; } });
 Object.defineProperty(exports, "SUPPORTED_CATALOG_SNAPSHOT_VERSIONS", { enumerable: true, get: function () { return movement_lang_1.SUPPORTED_CATALOG_SNAPSHOT_VERSIONS; } });
+Object.defineProperty(exports, "SUPPORTED_STORY_ANALYSIS_VERSIONS", { enumerable: true, get: function () { return movement_lang_1.SUPPORTED_STORY_ANALYSIS_VERSIONS; } });
 const protocol_1 = require("./protocol");
 /** A parked flow's state (docs/contracts/park-state.md). Engine to engine: a
  *  host stores it and hands it back. Version 2 is the Rust engine's; the earlier
@@ -46,6 +48,8 @@ exports.CONTRACTS = {
     },
     'adapter-protocol': { current: protocol_1.MANIFEST_PROTOCOL_VERSION, supported: [protocol_1.MANIFEST_PROTOCOL_VERSION], deprecated: [] },
     'system-caller': { current: exports.SYSTEM_CALLER_VERSION, supported: [exports.SYSTEM_CALLER_VERSION], deprecated: [] },
+    // The shape of what the check settled, for a surface that draws a movement's story (docs/contracts/story-analysis.md).
+    'story-analysis': { current: movement_lang_1.STORY_ANALYSIS_VERSION, supported: [...movement_lang_1.SUPPORTED_STORY_ANALYSIS_VERSIONS], deprecated: [] },
 };
 /** The language's contract (docs/contracts/language-versions.md) is not an
  *  integer of its own: it is the release's version, and a release reads the

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@listen-fire/engine-contracts",
   "license": "Apache-2.0",
-  "version": "0.12.0-rc.8",
+  "version": "0.12.1",
   "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.20.0"
+    "node": ">=22.23.4 <23"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -30,7 +30,7 @@
   "type": "commonjs",
   "dependencies": {
     "zod": "4.1.12",
-    "@listen-fire/movement-lang": "^0.12.0-rc.8"
+    "@listen-fire/movement-lang": "^0.12.1"
   },
   "devDependencies": {
     "@types/node": "20.16.5",
@@ -45,8 +45,7 @@
     "dist"
   ],
   "publishConfig": {
-    "access": "public",
-    "tag": "next"
+    "access": "public"
   },
   "scripts": {
     "code:type-check": "tsc --pretty --noEmit && node __embed_smoke__/check.cjs",