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

package/dist/public/limiter.js

@@ -3,7 +3,8 @@
 // (`limitRequest`, then `limited` around the call), the slot a host fills
 // (`installLimiter`), the in-process limiter a host starts from, and a
 // vendor's rate-limit wait read (`vendorWaitMs`) and turned into a throttle on
-// the caller's key (`throttleAfter`).
+// the caller's key (`throttleAfter`); a vendor's remaining budget on a success
+// (`vendorBudget`) closes the key early once it is spent (`budgetAfter`).
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);

package/dist/public/testing.d.ts

@@ -3,3 +3,5 @@ export * from '../services/run_host/contract';
 export * from '../services/browser/contract';
 export * from '../services/browser/fake_browser';
 export * from '../services/limiter/contract';
+export { RpcStoreBackend } from '../services/run_host/rpc_store';
+export type { NewDelivery, NewWorkRow } from '../services/run_host/rpc_store';

package/dist/public/testing.js

@@ -18,8 +18,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RpcStoreBackend = void 0;
 __exportStar(require("../services/movement_engine/test_host"), exports);
 __exportStar(require("../services/run_host/contract"), exports);
 __exportStar(require("../services/browser/contract"), exports);
 __exportStar(require("../services/browser/fake_browser"), exports);
 __exportStar(require("../services/limiter/contract"), exports);
+var rpc_store_1 = require("../services/run_host/rpc_store");
+Object.defineProperty(exports, "RpcStoreBackend", { enumerable: true, get: function () { return rpc_store_1.RpcStoreBackend; } });

package/dist/services/inbound/contract.d.ts

@@ -10,6 +10,10 @@ export interface ContractProvider {
     scheme: InboundSignatureScheme;
     signatureHeaders: string[];
     intercepts?: InboundIntercept[];
+    /** The header carrying the provider's id for each delivery. */
+    deliveryId?: {
+        header: string;
+    };
 }
 export interface ContractWorld {
     /** The providers the host serves itself. */
@@ -58,6 +62,21 @@ export interface InboundContractCase {
     run(backend: InboundContractBackend): Promise<void>;
 }
 export declare const INBOUND_CONTRACT_CASES: InboundContractCase[];
+/** A kept delivery, as the receipt cases read it. */
+export interface ContractDelivery {
+    externalId: string | null;
+    source: string;
+    eventCount: number;
+}
+export interface DeliveryReceiptContractBackend extends InboundContractBackend {
+    /** Every delivery the host kept, most recent first. */
+    deliveries(): Promise<ContractDelivery[]>;
+}
+export interface DeliveryReceiptContractCase {
+    name: string;
+    run(backend: DeliveryReceiptContractBackend): Promise<void>;
+}
+export declare const DELIVERY_RECEIPT_CONTRACT_CASES: DeliveryReceiptContractCase[];
 /** The world as an InboundStore + PushStore, for hosts whose doors are
  *  wired to injected stores (the express runner); a host with its own
  *  storage arranges the same world in it instead. */

package/dist/services/inbound/contract.js

@@ -20,7 +20,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INBOUND_CONTRACT_CASES = exports.CONTRACT_PUSH_TYPE = exports.CONTRACT_SLACK_KEY = exports.CONTRACT_PROVIDER_KEY = void 0;
+exports.DELIVERY_RECEIPT_CONTRACT_CASES = exports.INBOUND_CONTRACT_CASES = exports.CONTRACT_PUSH_TYPE = exports.CONTRACT_SLACK_KEY = exports.CONTRACT_PROVIDER_KEY = void 0;
 exports.memoryInboundStores = memoryInboundStores;
 const strict_1 = __importDefault(require("node:assert/strict"));
 const node_crypto_1 = require("node:crypto");
@@ -370,6 +370,103 @@ exports.INBOUND_CONTRACT_CASES = [
         },
     },
 ];
+const CRM_WITH_IDS = { ...CRM, deliveryId: { header: 'x-crm-delivery' } };
+const withIds = (overrides = {}) => ({ providers: [CRM_WITH_IDS, SLACK], ...overrides });
+const crmSignedAs = (id) => (body) => ({ ...crmSigned(body), 'x-crm-delivery': id });
+const EMIT_DOOR = `/api/public/adapter/${exports.CONTRACT_PUSH_TYPE}/emit`;
+const pushCredential = () => ({ authorization: 'Bearer push-credential' });
+exports.DELIVERY_RECEIPT_CONTRACT_CASES = [
+    {
+        name: 'a delivery is kept under the id its declared header carries',
+        async run(backend) {
+            await arrangeAnd(backend, withIds());
+            const answer = await post(backend, CRM_DOOR, json(TWO_EVENTS), crmSignedAs('d-1'));
+            strict_1.default.deepEqual([answer.status, answer.body], [200, { ok: true, eventsProcessed: 2 }]);
+            strict_1.default.deepEqual(await backend.deliveries(), [{ externalId: 'd-1', source: 'webhook', eventCount: 2 }]);
+        },
+    },
+    {
+        name: 'a redelivery under the same id is acked as a duplicate and queues nothing',
+        async run(backend) {
+            await arrangeAnd(backend, withIds());
+            const first = await post(backend, CRM_DOOR, json({ ...TWO_EVENTS, checkpoint: { cursor: 'c-1' } }), crmSignedAs('d-1'));
+            strict_1.default.equal(first.status, 200);
+            const again = await post(backend, CRM_DOOR, json({ ...TWO_EVENTS, checkpoint: { cursor: 'c-2' } }), crmSignedAs('d-1'));
+            strict_1.default.deepEqual([again.status, again.body], [200, { ok: true, duplicate: true, eventsProcessed: 0 }]);
+            const seen = await backend.observed();
+            strict_1.default.deepEqual([seen.enqueued, seen.checkpoints.length, seen.notified], [2, 1, 1]);
+            strict_1.default.equal((await backend.deliveries()).length, 1);
+        },
+    },
+    {
+        name: 'without the header each delivery is its own, and none is a duplicate',
+        async run(backend) {
+            await arrangeAnd(backend, withIds());
+            for (let i = 0; i < 2; i += 1) {
+                const answer = await post(backend, CRM_DOOR, json(TWO_EVENTS), crmSigned);
+                strict_1.default.deepEqual([answer.status, answer.body], [200, { ok: true, eventsProcessed: 2 }]);
+            }
+            strict_1.default.equal((await backend.observed()).enqueued, 4);
+            const kept = await backend.deliveries();
+            strict_1.default.deepEqual(kept.map((d) => d.externalId), [null, null]);
+        },
+    },
+    {
+        name: 'the same id at another subscription is not a duplicate',
+        async run(backend) {
+            await arrangeAnd(backend, withIds({
+                subscriptions: [
+                    { id: 'sub-crm', teamId: TEAM, providerKey: exports.CONTRACT_PROVIDER_KEY, secret: SECRET },
+                    { id: 'sub-crm-2', teamId: TEAM, providerKey: exports.CONTRACT_PROVIDER_KEY, secret: SECRET },
+                ],
+            }));
+            for (const subscription of ['sub-crm', 'sub-crm-2']) {
+                const answer = await post(backend, door('contract_crm', subscription), json(TWO_EVENTS), crmSignedAs('d-1'));
+                strict_1.default.deepEqual([answer.status, answer.body], [200, { ok: true, eventsProcessed: 2 }]);
+            }
+            strict_1.default.equal((await backend.observed()).enqueued, 4);
+            strict_1.default.deepEqual((await backend.deliveries()).map((d) => d.externalId), ['d-1', 'd-1']);
+        },
+    },
+    {
+        name: 'a delivery whose wakes failed is kept without its id, so the retry is kept too',
+        async run(backend) {
+            await arrangeAnd(backend, withIds({ faults: { wakeKeys: true } }));
+            for (let i = 0; i < 2; i += 1) {
+                const answer = await post(backend, CRM_DOOR, json(TWO_EVENTS), crmSignedAs('d-1'));
+                strict_1.default.equal(answer.status, 500);
+            }
+            strict_1.default.equal((await backend.observed()).enqueued, 4);
+            strict_1.default.deepEqual((await backend.deliveries()).map((d) => d.externalId), [null, null]);
+        },
+    },
+    {
+        name: "emit's deliveryId keeps the batch out the second time",
+        async run(backend) {
+            await arrangeAnd(backend);
+            const batch = json({ events: [{ payload: { n: 1 } }], deliveryId: 'b-1' });
+            const first = await post(backend, EMIT_DOOR, batch, pushCredential);
+            strict_1.default.deepEqual([first.status, first.body], [202, { accepted: 1 }]);
+            const again = await post(backend, EMIT_DOOR, batch, pushCredential);
+            strict_1.default.deepEqual([again.status, again.body], [202, { accepted: 0, duplicate: true }]);
+            const seen = await backend.observed();
+            strict_1.default.deepEqual([seen.enqueued, seen.notified], [1, 1]);
+            strict_1.default.deepEqual(await backend.deliveries(), [{ externalId: 'b-1', source: 'emit', eventCount: 1 }]);
+        },
+    },
+    {
+        name: "an emit's deliveryId that is not a non-empty string is a 400",
+        async run(backend) {
+            await arrangeAnd(backend);
+            for (const deliveryId of ['', 7, null]) {
+                const answer = await post(backend, EMIT_DOOR, json({ events: [{ payload: { n: 1 } }], deliveryId }), pushCredential);
+                strict_1.default.equal(answer.status, 400);
+                strict_1.default.deepEqual(answer.body.issues?.[0]?.path, 'deliveryId');
+            }
+            strict_1.default.deepEqual(await backend.deliveries(), []);
+        },
+    },
+];
 // ── A reference backend's stores, in memory ───────────────────────────────
 /** The world as an InboundStore + PushStore, for hosts whose doors are
  *  wired to injected stores (the express runner); a host with its own

package/dist/services/limiter/contract.js

@@ -34,6 +34,18 @@ function refusedUntil(grant) {
     strict_1.default.ok(Number.isFinite(at), `retryAt ${grant.retryAt} is an instant`);
     return at;
 }
+/** A grant, with the instants either side of the request: the limiter
+ *  counted the call somewhere between them. */
+async function granted(limiter, at) {
+    const before = Date.now();
+    permitOf(await limiter.acquire(at));
+    return { before, after: Date.now() };
+}
+/** `instant` is `call` plus `windowMs`, within the call's request (a
+ *  millisecond of slack for a limiter rounding to whole milliseconds). */
+function assertBetween(instant, call, windowMs, message) {
+    strict_1.default.ok(instant >= call.before + windowMs - 1 && instant <= call.after + windowMs + 1, `${message}: retryAt is ${instant - call.before - windowMs}ms after the call's request plus the window, expected within ${call.after - call.before}ms`);
+}
 exports.limiterContractCases = [
     {
         name: 'a call under no limit is granted, and releasing a permit twice, or one never given, changes nothing',
@@ -69,6 +81,31 @@ exports.limiterContractCases = [
             permitOf(await limiter.acquire(at));
         },
     },
+    {
+        // A token bucket refills while the window still holds the burst, so a
+        // burst then a trickle puts nearly twice the calls in one window. Calls
+        // are spaced well apart so the wire's latency cannot blur which have left.
+        name: 'a rolling window never holds more than the declared calls',
+        async run(limiter) {
+            const at = request([{ key: key('rolling'), calls: 3, perMs: 1_000 }]);
+            const first = await granted(limiter, at);
+            await sleep(300);
+            const second = await granted(limiter, at);
+            await granted(limiter, at);
+            await sleep(first.before + 500 - Date.now());
+            // The bucket would have refilled one call by now; the window still holds three.
+            const oldestLeaves = refusedUntil(await limiter.acquire(at));
+            assertBetween(oldestLeaves, first, 1_000, 'refused until the oldest call leaves the window');
+            await sleep(oldestLeaves - Date.now() + 20);
+            const fourth = await granted(limiter, at);
+            const nextLeaves = refusedUntil(await limiter.acquire(at));
+            assertBetween(nextLeaves, second, 1_000, 'exactly one call left, so one more; then refused until the next leaves');
+            await sleep(nextLeaves - Date.now() + 20);
+            await granted(limiter, at);
+            await granted(limiter, at);
+            assertBetween(refusedUntil(await limiter.acquire(at)), fourth, 1_000, 'two left, so two more, and no third');
+        },
+    },
     {
         name: 'a call costing more counts for more against a rate limit',
         async run(limiter) {

package/dist/services/limiter/limiter.d.ts

@@ -1,9 +1,10 @@
 import type { WireDeclaredLimitShape } from '@listen-fire/engine-contracts';
-export { vendorWaitMs } from '@listen-fire/module-runtime/vendor_wait';
+import { type VendorBudget } from '@listen-fire/module-runtime/vendor_wait';
+export { vendorBudget, vendorWaitMs, type VendorBudget } from '@listen-fire/module-runtime/vendor_wait';
 /** One limit a request is under, resolved to the bucket it counts in. */
 export interface LimitBucket {
     key: string;
-    /** At most `calls` per `perMs`; the two go together. */
+    /** At most `calls` in any `perMs` (a rolling window); the two go together. */
     calls?: number;
     perMs?: number;
     concurrent?: number;
@@ -69,12 +70,37 @@ export declare function limited<T>(limiter: Limiter, request: LimitRequest, call
  *  throttle on `caller`'s key: every call made as that caller, by any host
  *  sharing `limiter`, is refused until then, and `acquireOrWait` waits it out. */
 export declare function throttleAfter(limiter: Limiter, caller: Caller, waitMs: number, now?: number): Promise<void>;
+/** A vendor's budget reported on a success (`vendorBudget`), taken early: a
+ *  vendor out of budget (`remaining` 0) closes the caller's key until it
+ *  resets, as its 429 would, so the next call waits rather than earning one.
+ *  A count above zero changes nothing. The window the limiter keeps is the
+ *  module's declared budget, which the module's author set on purpose; the
+ *  vendor's count is advisory (shared with other clients of the same key,
+ *  stale by the time it is read), so it is never used to reshape that window. */
+export declare function budgetAfter(limiter: Limiter, caller: Caller, budget: VendorBudget | undefined, now?: number): Promise<void>;
 /** The limiter filling the slot: the built-in until a host installs another. */
 export declare function limiterSlot(): Limiter;
 export declare function installLimiter(limiter: Limiter): void;
-/** The limits kept in this process: a token bucket per `calls`/`perMs` limit
- *  (full at first, refilled evenly), a count of held permits per
- *  `concurrent` one, and the throttles providers reported. */
+/** One call counted in a rate limit's window: when it was granted, and for how much. */
+export interface WindowCall {
+    at: number;
+    cost: number;
+}
+/** What one call counts for in a window of `calls`: a call costing more
+ *  than the whole window takes all of it, so it waits for an empty one. */
+export declare function windowCost(cost: number, calls: number): number;
+/** The calls still in the window at `now`: a call granted at `at` leaves it at `at + perMs`. */
+export declare function inWindow(calls: readonly WindowCall[], perMs: number, now: number): WindowCall[];
+/** When a call costing `cost` fits a window of `limit.calls` per `limit.perMs`
+ *  already holding `window` (in it at `now`, oldest first): undefined if it
+ *  fits now, else the instant enough of the oldest calls have left. */
+export declare function windowRetryAt(window: readonly WindowCall[], limit: {
+    calls: number;
+    perMs: number;
+}, cost: number): number | undefined;
+/** The limits kept in this process: the calls in each `calls`/`perMs`
+ *  limit's rolling window, a count of held permits per `concurrent` one,
+ *  and the throttles providers reported. */
 export declare class MemoryLimiter implements Limiter {
     private readonly buckets;
     private readonly permits;

package/dist/services/limiter/limiter.js

@@ -12,17 +12,22 @@
 // a manifest. The built-in, `@lf/memory-limiter`, keeps them in this process
 // (`MemoryLimiter`); lf's Rust one is the same (crates/lf/src/limiter.rs).
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryLimiter = exports.HOLD_MS = exports.vendorWaitMs = void 0;
+exports.MemoryLimiter = exports.HOLD_MS = exports.vendorWaitMs = exports.vendorBudget = void 0;
 exports.throttleKey = throttleKey;
 exports.durationMs = durationMs;
 exports.limitRequest = limitRequest;
 exports.acquireOrWait = acquireOrWait;
 exports.limited = limited;
 exports.throttleAfter = throttleAfter;
+exports.budgetAfter = budgetAfter;
 exports.limiterSlot = limiterSlot;
 exports.installLimiter = installLimiter;
+exports.windowCost = windowCost;
+exports.inWindow = inWindow;
+exports.windowRetryAt = windowRetryAt;
 const node_crypto_1 = require("node:crypto");
 var vendor_wait_1 = require("@listen-fire/module-runtime/vendor_wait");
+Object.defineProperty(exports, "vendorBudget", { enumerable: true, get: function () { return vendor_wait_1.vendorBudget; } });
 Object.defineProperty(exports, "vendorWaitMs", { enumerable: true, get: function () { return vendor_wait_1.vendorWaitMs; } });
 /** No call outlives a segment's wall clock (its default), so a permit its
  *  holder never released lapses then. */
@@ -110,6 +115,18 @@ async function limited(limiter, request, call) {
 async function throttleAfter(limiter, caller, waitMs, now = Date.now()) {
     await limiter.throttle({ key: throttleKey(caller), until: new Date(now + waitMs).toISOString() });
 }
+/** A vendor's budget reported on a success (`vendorBudget`), taken early: a
+ *  vendor out of budget (`remaining` 0) closes the caller's key until it
+ *  resets, as its 429 would, so the next call waits rather than earning one.
+ *  A count above zero changes nothing. The window the limiter keeps is the
+ *  module's declared budget, which the module's author set on purpose; the
+ *  vendor's count is advisory (shared with other clients of the same key,
+ *  stale by the time it is read), so it is never used to reshape that window. */
+async function budgetAfter(limiter, caller, budget, now = Date.now()) {
+    if (budget === undefined || budget.remaining > 0 || budget.resetAt <= now)
+        return;
+    await throttleAfter(limiter, caller, budget.resetAt - now, now);
+}
 // ── The slot this process's calls ask ───────────────────────────────────────
 let slot;
 /** The limiter filling the slot: the built-in until a host installs another. */
@@ -120,13 +137,38 @@ function limiterSlot() {
 function installLimiter(limiter) {
     slot = limiter;
 }
+/** What one call counts for in a window of `calls`: a call costing more
+ *  than the whole window takes all of it, so it waits for an empty one. */
+function windowCost(cost, calls) {
+    return Math.min(cost, calls);
+}
+/** The calls still in the window at `now`: a call granted at `at` leaves it at `at + perMs`. */
+function inWindow(calls, perMs, now) {
+    return calls.filter((call) => call.at + perMs > now);
+}
+/** When a call costing `cost` fits a window of `limit.calls` per `limit.perMs`
+ *  already holding `window` (in it at `now`, oldest first): undefined if it
+ *  fits now, else the instant enough of the oldest calls have left. */
+function windowRetryAt(window, limit, cost) {
+    let held = window.reduce((sum, call) => sum + call.cost, 0);
+    const needed = windowCost(cost, limit.calls);
+    if (held + needed <= limit.calls)
+        return undefined;
+    for (const call of window) {
+        held -= call.cost;
+        if (held + needed <= limit.calls)
+            return call.at + limit.perMs;
+    }
+    // Unreachable while every call in the window costs at most `limit.calls`.
+    return undefined;
+}
 // ── @lf/memory-limiter ──────────────────────────────────────────────────────
 /** How soon a call refused for concurrency asks again, if no release wakes
  *  it first (a permit lapsing frees a place with no release). */
 const CONCURRENCY_RECHECK_MS = 1_000;
-/** The limits kept in this process: a token bucket per `calls`/`perMs` limit
- *  (full at first, refilled evenly), a count of held permits per
- *  `concurrent` one, and the throttles providers reported. */
+/** The limits kept in this process: the calls in each `calls`/`perMs`
+ *  limit's rolling window, a count of held permits per `concurrent` one,
+ *  and the throttles providers reported. */
 class MemoryLimiter {
     buckets = new Map();
     permits = new Map();
@@ -144,15 +186,12 @@ class MemoryLimiter {
         let retryAt;
         const later = (at) => (retryAt = retryAt === undefined ? at : Math.max(retryAt, at));
         for (const limit of request.limits) {
-            const bucket = this.bucket(limit, now);
+            const bucket = this.bucket(limit);
             if (limit.calls !== undefined && limit.perMs !== undefined) {
-                const rate = limit.calls / limit.perMs;
-                bucket.tokens = Math.min(limit.calls, bucket.tokens + (now - bucket.filledAt) * rate);
-                bucket.filledAt = now;
-                // A call costing more than the whole window waits for a full one.
-                const cost = Math.min(request.cost, limit.calls);
-                if (bucket.tokens < cost)
-                    later(now + Math.ceil((cost - bucket.tokens) / rate));
+                bucket.calls = inWindow(bucket.calls, limit.perMs, now);
+                const room = windowRetryAt(bucket.calls, { calls: limit.calls, perMs: limit.perMs }, request.cost);
+                if (room !== undefined)
+                    later(room);
             }
             if (limit.concurrent !== undefined && bucket.held >= limit.concurrent) {
                 const soonestLapse = Math.min(...[...this.permits.values()].map((p) => p.lapsesAt));
@@ -163,9 +202,9 @@ class MemoryLimiter {
             return { granted: false, retryAt: new Date(retryAt).toISOString() };
         const holds = [];
         for (const limit of request.limits) {
-            const bucket = this.bucket(limit, now);
-            if (limit.calls !== undefined)
-                bucket.tokens -= Math.min(request.cost, limit.calls);
+            const bucket = this.bucket(limit);
+            if (limit.calls !== undefined && limit.perMs !== undefined)
+                bucket.calls.push({ at: now, cost: windowCost(request.cost, limit.calls) });
             if (limit.concurrent !== undefined) {
                 bucket.held += 1;
                 holds.push(limit.key);
@@ -192,10 +231,10 @@ class MemoryLimiter {
         this.waiters.add(wake);
         return { wait, stop: () => this.waiters.delete(wake) };
     }
-    bucket(limit, now) {
+    bucket(limit) {
         let bucket = this.buckets.get(limit.key);
         if (bucket === undefined) {
-            bucket = { tokens: limit.calls ?? 0, filledAt: now, held: 0 };
+            bucket = { calls: [], held: 0 };
             this.buckets.set(limit.key, bucket);
         }
         return bucket;

package/dist/services/plugins/registry.js

@@ -511,6 +511,11 @@ const WEB_RENDER_SIGNATURE = {
             description: 'The page: "a4" (the default) or "letter".',
         },
         { name: 'margin', type: { kind: 'number' }, description: 'The margin on every side, in points (a whole number from 0 to 200). The default is 30.' },
+        {
+            name: 'name',
+            type: { kind: 'string' },
+            description: 'The file\'s name, as the system it is written to shows it: ".pdf" is added when it does not end with it. The default is "movement-artifact.pdf".',
+        },
     ],
     dataDependency: 'none',
     // The browser may load the images and styles an HTML page names.

package/dist/services/run_host/contract.d.ts

@@ -1,5 +1,6 @@
 import { type RunRecords } from './rules';
-import type { CallbackStore, RunHostStore } from './store';
+import type { CallbackStore, ClaimedWork, RunHostStore } from './store';
+import type { DeliveryRow, NewDelivery, NewWorkRow, RunRow } from './rpc_store';
 export interface ContractBackend {
     store: RunHostStore;
     /** The tenant every run of the case belongs to. */
@@ -34,3 +35,55 @@ export interface RecordsContractCase {
 }
 export declare const callbackContractCases: RecordsContractCase[];
 export declare const cancelContractCases: RecordsContractCase[];
+export interface DeliveryContractBackend {
+    /** The tenant every row of the case belongs to. */
+    teamId: string;
+    keepDelivery(input: {
+        subscriptionId: string;
+        checkpoint?: unknown;
+        delivery: NewDelivery;
+        work: NewWorkRow[];
+    }): Promise<{
+        kept: boolean;
+    }>;
+    deliveries(input: {
+        subscriptionId?: string | null;
+        since?: string | null;
+        limit: number;
+    }): Promise<DeliveryRow[]>;
+    delivery(input: {
+        id: string;
+    }): Promise<DeliveryRow | null>;
+    sweepDeliveries(input: {
+        before: string;
+        limit: number;
+    }): Promise<number>;
+    /** The subscription's saved pull cursor. */
+    checkpoint(input: {
+        subscriptionId: string;
+    }): Promise<{
+        checkpoint: unknown;
+    } | null>;
+    startRun(input: {
+        id: string;
+        file: string;
+        movement: string;
+        startedAt: string;
+        input: string;
+        deliveryId?: string;
+    }): Promise<void>;
+    completeRun(runId: string): Promise<void>;
+    runGet(input: {
+        runId: string;
+    }): Promise<RunRow | null>;
+    claimDue(input: {
+        limit: number;
+        leaseMs: number;
+        kinds?: readonly string[];
+    }): Promise<ClaimedWork[]>;
+}
+export interface DeliveryContractCase {
+    name: string;
+    run(backend: DeliveryContractBackend): Promise<void>;
+}
+export declare const deliveryContractCases: DeliveryContractCase[];

package/dist/services/run_host/contract.js

@@ -13,8 +13,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cancelContractCases = exports.callbackContractCases = exports.runHostContractCases = void 0;
+exports.deliveryContractCases = exports.cancelContractCases = exports.callbackContractCases = exports.runHostContractCases = void 0;
 const strict_1 = __importDefault(require("node:assert/strict"));
+const node_crypto_1 = require("node:crypto");
 const errors_1 = require("../movement_engine/errors");
 const drain_1 = require("./drain");
 const rules_1 = require("./rules");
@@ -932,3 +933,160 @@ exports.cancelContractCases = [
         },
     },
 ];
+const DAYS = (days) => PAST(days * 24 * 60);
+function newDelivery(extra = {}) {
+    return {
+        id: (0, node_crypto_1.randomUUID)(),
+        externalId: null,
+        receivedAt: new Date().toISOString(),
+        source: 'webhook',
+        inline: false,
+        replayOf: null,
+        events: [{ external: 'crm', event: { n: 1 } }],
+        ...extra,
+    };
+}
+/** One of the delivery's events queued for the drain, as lf's doors queue it. */
+function fireRow(deliveryId, n) {
+    return { kind: 'fire_event', key: uniqueKey('fire_event'), payload: { external: 'crm', event: { n }, deliveryId }, dueAt: PAST(1), teamId: null };
+}
+async function claimedKeys(backend, keys) {
+    const claimed = await backend.claimDue({ limit: 1000, leaseMs: 60_000, kinds: ['fire_event'] });
+    return claimed.filter((w) => keys.includes(w.key));
+}
+async function startDeliveryRun(backend, deliveryId) {
+    const id = (0, node_crypto_1.randomUUID)();
+    await backend.startRun({ id, file: 'f', movement: 'm', startedAt: new Date().toISOString(), input: '{}', ...(deliveryId !== undefined ? { deliveryId } : {}) });
+    return id;
+}
+/** A first delivery under `externalId`, then its redelivery (a new id, another
+ *  cursor, another row): the second is kept out and leaves nothing. */
+async function redelivered(backend, opts) {
+    const subscriptionId = uniqueKey('sub');
+    const externalId = uniqueKey('delivery');
+    const first = newDelivery({ externalId });
+    const firstRow = fireRow(first.id, 1);
+    strict_1.default.deepEqual(await backend.keepDelivery({ subscriptionId, checkpoint: { cursor: 'c-1' }, delivery: first, work: [firstRow] }), { kept: true });
+    if (opts.claimBetween) {
+        const [claimed] = await claimedKeys(backend, [firstRow.key]);
+        strict_1.default.ok(claimed, "the first's row was queued");
+    }
+    const second = newDelivery({ externalId });
+    const secondRow = fireRow(second.id, 2);
+    strict_1.default.deepEqual(await backend.keepDelivery({ subscriptionId, checkpoint: { cursor: 'c-2' }, delivery: second, work: [secondRow] }), { kept: false });
+    strict_1.default.deepEqual(await backend.checkpoint({ subscriptionId }), { checkpoint: { cursor: 'c-1' } }, "the cursor is still the first's");
+    strict_1.default.deepEqual(await claimedKeys(backend, [secondRow.key]), [], 'the redelivery queued nothing');
+    strict_1.default.equal(await backend.delivery({ id: second.id }), null);
+    strict_1.default.deepEqual((await backend.deliveries({ subscriptionId, limit: 10 })).map((d) => d.id), [first.id]);
+}
+exports.deliveryContractCases = [
+    {
+        name: 'deliveries: a delivery is kept with its work as one write',
+        async run(backend) {
+            const subscriptionId = uniqueKey('sub');
+            const delivery = newDelivery({ externalId: uniqueKey('delivery'), events: [{ external: 'crm', event: { n: 1 } }, { external: 'crm', event: { n: 2 } }] });
+            const work = [fireRow(delivery.id, 1), fireRow(delivery.id, 2)];
+            strict_1.default.deepEqual(await backend.keepDelivery({ subscriptionId, checkpoint: { cursor: 'c-1' }, delivery, work }), { kept: true });
+            const keys = work.map((w) => w.key);
+            strict_1.default.deepEqual((await claimedKeys(backend, keys)).map((w) => w.key).sort(), [...keys].sort());
+            strict_1.default.deepEqual(await backend.checkpoint({ subscriptionId }), { checkpoint: { cursor: 'c-1' } });
+            strict_1.default.deepEqual(await backend.delivery({ id: delivery.id }), {
+                id: delivery.id,
+                subscriptionId,
+                externalId: delivery.externalId,
+                receivedAt: delivery.receivedAt,
+                source: 'webhook',
+                inline: false,
+                replayOf: null,
+                eventCount: 2,
+                runs: [],
+                events: delivery.events,
+            });
+        },
+    },
+    {
+        name: 'deliveries: a duplicate externalId is not kept, and writes nothing',
+        run: (backend) => redelivered(backend, { claimBetween: true }),
+    },
+    {
+        name: "deliveries: a redelivery while the first's work is still queued is kept out",
+        run: (backend) => redelivered(backend, { claimBetween: false }),
+    },
+    {
+        name: 'deliveries: the same externalId on another subscription, or none, is kept',
+        async run(backend) {
+            const [one, other] = [uniqueKey('sub'), uniqueKey('sub')];
+            const externalId = uniqueKey('delivery');
+            const keep = async (subscriptionId, delivery) => (await backend.keepDelivery({ subscriptionId, delivery, work: [] })).kept;
+            const kept = [newDelivery({ externalId }), newDelivery({ externalId }), newDelivery(), newDelivery()];
+            strict_1.default.equal(await keep(one, kept[0]), true);
+            strict_1.default.equal(await keep(other, kept[1]), true, 'another subscription');
+            strict_1.default.equal(await keep(one, kept[2]), true, 'no external id');
+            strict_1.default.equal(await keep(one, kept[3]), true, 'no external id, again');
+            const listed = (await backend.deliveries({ limit: 100 })).map((d) => d.id);
+            for (const delivery of kept)
+                strict_1.default.ok(listed.includes(delivery.id), delivery.id);
+        },
+    },
+    {
+        name: 'deliveries: a delivery lists its runs',
+        async run(backend) {
+            const subscriptionId = uniqueKey('sub');
+            const delivery = newDelivery();
+            await backend.keepDelivery({ subscriptionId, delivery, work: [] });
+            const running = await startDeliveryRun(backend, delivery.id);
+            const completed = await startDeliveryRun(backend, delivery.id);
+            const unnamed = await startDeliveryRun(backend, undefined);
+            await backend.completeRun(completed);
+            const [row] = await backend.deliveries({ subscriptionId, limit: 10 });
+            const byId = (a, b) => a.id.localeCompare(b.id);
+            strict_1.default.deepEqual([...(row?.runs ?? [])].sort(byId), [
+                { id: running, status: 'running' },
+                { id: completed, status: 'completed' },
+            ].sort(byId));
+            strict_1.default.equal(row?.events, undefined, 'a listing carries no events');
+            strict_1.default.equal((await backend.runGet({ runId: running }))?.deliveryId, delivery.id);
+            strict_1.default.equal((await backend.runGet({ runId: unnamed }))?.deliveryId, null);
+        },
+    },
+    {
+        name: 'deliveries: listing filters by subscription and since, most recent first, at most limit',
+        async run(backend) {
+            const [one, other] = [uniqueKey('sub'), uniqueKey('sub')];
+            const at = (minutesAgo) => newDelivery({ receivedAt: PAST(minutesAgo) });
+            const [oldest, middle, newest, elsewhere] = [at(30), at(20), at(10), at(5)];
+            for (const [subscriptionId, delivery] of [[one, oldest], [one, middle], [one, newest], [other, elsewhere]]) {
+                await backend.keepDelivery({ subscriptionId, delivery, work: [] });
+            }
+            const ids = async (input) => (await backend.deliveries(input)).map((d) => d.id);
+            strict_1.default.deepEqual(await ids({ subscriptionId: one, limit: 10 }), [newest.id, middle.id, oldest.id]);
+            strict_1.default.deepEqual(await ids({ subscriptionId: one, since: middle.receivedAt, limit: 10 }), [newest.id, middle.id]);
+            strict_1.default.deepEqual(await ids({ subscriptionId: one, limit: 1 }), [newest.id]);
+            const all = await ids({ limit: 100 });
+            strict_1.default.deepEqual(all.filter((id) => [oldest.id, middle.id, newest.id, elsewhere.id].includes(id)), [elsewhere.id, newest.id, middle.id, oldest.id]);
+        },
+    },
+    {
+        name: 'deliveries: the sweep forgets settled old deliveries only',
+        async run(backend) {
+            const subscriptionId = uniqueKey('sub');
+            const old = async (work = () => []) => {
+                const delivery = newDelivery({ receivedAt: DAYS(30) });
+                await backend.keepDelivery({ subscriptionId, delivery, work: work(delivery.id) });
+                return delivery.id;
+            };
+            const settled = await old();
+            await backend.completeRun(await startDeliveryRun(backend, settled));
+            const running = await old();
+            await startDeliveryRun(backend, running);
+            const queued = await old((id) => [{ ...fireRow(id, 1), dueAt: FUTURE(60) }]);
+            const fresh = newDelivery();
+            await backend.keepDelivery({ subscriptionId, delivery: fresh, work: [] });
+            strict_1.default.equal(await backend.sweepDeliveries({ before: DAYS(14), limit: 100 }), 1);
+            strict_1.default.equal(await backend.delivery({ id: settled }), null, 'old, its run settled: forgotten');
+            strict_1.default.ok(await backend.delivery({ id: running }), 'its run is still running');
+            strict_1.default.ok(await backend.delivery({ id: queued }), 'a fire_event row still names it');
+            strict_1.default.ok(await backend.delivery({ id: fresh.id }), 'not old enough');
+        },
+    },
+];

package/dist/services/run_host/rpc_store.d.ts

@@ -2,6 +2,55 @@ import { z } from 'zod';
 import { type SlotAddress } from '@listen-fire/module-runtime/module_wire/wire';
 import type { RunRecords } from './rules';
 import type { CallbackStore, RunHostStore } from './store';
+export declare const DELIVERY_SOURCES: readonly ["webhook", "hook", "emit", "cli"];
+export type DeliverySource = (typeof DELIVERY_SOURCES)[number];
+/** `inbound.keepDelivery`'s `delivery`. */
+export interface NewDelivery {
+    id: string;
+    /** The provider's id for the delivery: a second one under it, at the same subscription, is kept out. */
+    externalId?: string | null;
+    receivedAt: string;
+    source: DeliverySource;
+    inline: boolean;
+    replayOf?: string | null;
+    events: unknown[];
+}
+/** A work row as `inbound.keepDelivery` queues it (`work.enqueue`'s input). */
+export interface NewWorkRow {
+    kind: string;
+    key: string;
+    payload: unknown;
+    dueAt?: string | null;
+    teamId?: string | null;
+}
+export interface DeliveryRun {
+    id: string;
+    status: string;
+}
+/** A kept delivery; `events` only from `inbound.delivery`. */
+export interface DeliveryRow {
+    id: string;
+    subscriptionId: string;
+    externalId: string | null;
+    receivedAt: string;
+    source: DeliverySource;
+    inline: boolean;
+    replayOf: string | null;
+    eventCount: number;
+    runs: DeliveryRun[];
+    events?: unknown[];
+}
+/** A run row as `runs.get` answers it. */
+export interface RunRow {
+    id: string;
+    file: string;
+    movement: string;
+    status: string;
+    startedAt: string;
+    input: string;
+    outcome: string | null;
+    deliveryId: string | null;
+}
 export declare class RpcStoreBackend {
     readonly store: RunHostStore;
     readonly callbacks: CallbackStore;
@@ -14,14 +63,51 @@ export declare class RpcStoreBackend {
     /** One call; its result read by `schema`. A fenced write refused because
      *  the run's lease is gone throws the core's `RunLeaseLost`. */
     call<S extends z.ZodType>(method: string, params: object, schema: S): Promise<z.infer<S>>;
-    /** A run row the backend can park against (the contract's `newRun`). */
+    /** A run row the backend can park against (the contract's `newRun`);
+     *  `deliveryId` names the delivery whose event started it. */
     startRun(input: {
         id: string;
         file: string;
         movement: string;
         startedAt: string;
         input: string;
+        deliveryId?: string;
     }): Promise<void>;
+    /** A run's row, or null (`runs.get`). */
+    runGet(input: {
+        runId: string;
+    }): Promise<RunRow | null>;
+    /** The door's one write: the receipt, the cursor (absent: left as it is)
+     *  and the work rows; `kept: false`, and nothing written, for a duplicate. */
+    keepDelivery(input: {
+        subscriptionId: string;
+        checkpoint?: unknown;
+        delivery: NewDelivery;
+        work: NewWorkRow[];
+    }): Promise<{
+        kept: boolean;
+    }>;
+    /** Kept deliveries, most recent first, without their events. */
+    deliveries(input: {
+        subscriptionId?: string | null;
+        since?: string | null;
+        limit: number;
+    }): Promise<DeliveryRow[]>;
+    /** One kept delivery with its events, or null. */
+    delivery(input: {
+        id: string;
+    }): Promise<DeliveryRow | null>;
+    /** Forget settled deliveries received before `before`: how many went. */
+    sweepDeliveries(input: {
+        before: string;
+        limit: number;
+    }): Promise<number>;
+    /** A subscription's saved pull cursor (`inbound.checkpoint`). */
+    checkpoint(input: {
+        subscriptionId: string;
+    }): Promise<{
+        checkpoint: unknown;
+    } | null>;
     /** An operator asks to cancel the run (the records contract's `requestCancel`). */
     requestCancel(input: {
         runId: string;

package/dist/services/run_host/rpc_store.js

@@ -13,7 +13,7 @@
 // `run_lease_lost` (`data: { runId }`) is rethrown as the core's
 // `RunLeaseLost`, so the rules over the store see the one refusal they handle.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RpcStoreBackend = void 0;
+exports.RpcStoreBackend = exports.DELIVERY_SOURCES = void 0;
 const zod_1 = require("zod");
 const engine_contracts_1 = require("@listen-fire/engine-contracts");
 const slots_1 = require("@listen-fire/engine-contracts/slots");
@@ -47,6 +47,33 @@ const Claim = zod_1.z.discriminatedUnion('kind', [
     zod_1.z.object({ kind: zod_1.z.literal('closed'), callback: Callback }),
     zod_1.z.object({ kind: zod_1.z.literal('expired'), callback: Callback }),
 ]);
+// ── Delivery receipts (`inbound.*`) ─────────────────────────────────────────
+// What a door keeps of one delivery: the events it produced, in the door's one
+// write. Only lf's doors call these, so they live on this client rather than
+// on `RunHostStore`.
+exports.DELIVERY_SOURCES = ['webhook', 'hook', 'emit', 'cli'];
+const Delivery = zod_1.z.object({
+    id: zod_1.z.string(),
+    subscriptionId: zod_1.z.string(),
+    externalId: zod_1.z.string().nullable(),
+    receivedAt: zod_1.z.string(),
+    source: zod_1.z.enum(exports.DELIVERY_SOURCES),
+    inline: zod_1.z.boolean(),
+    replayOf: zod_1.z.string().nullable(),
+    eventCount: zod_1.z.number(),
+    runs: zod_1.z.array(zod_1.z.object({ id: zod_1.z.string(), status: zod_1.z.string() })),
+    events: zod_1.z.array(zod_1.z.unknown()).optional(),
+});
+const Run = zod_1.z.object({
+    id: zod_1.z.string(),
+    file: zod_1.z.string(),
+    movement: zod_1.z.string(),
+    status: zod_1.z.string(),
+    startedAt: zod_1.z.string(),
+    input: zod_1.z.string(),
+    outcome: zod_1.z.string().nullable(),
+    deliveryId: zod_1.z.string().nullable(),
+});
 /** The work claim the server reads: no more than it needs, whatever the caller spreads in. */
 function claimOf(work) {
     return { id: work.id, kind: work.kind, key: work.key, claim: work.claim, ...(work.dueAt !== undefined ? { dueAt: work.dueAt } : {}) };
@@ -83,9 +110,42 @@ class RpcStoreBackend {
             throw error;
         }
     }
-    /** A run row the backend can park against (the contract's `newRun`). */
+    /** A run row the backend can park against (the contract's `newRun`);
+     *  `deliveryId` names the delivery whose event started it. */
     async startRun(input) {
-        await this.call('runs.start', input, Nothing);
+        await this.call('runs.start', { ...input, deliveryId: input.deliveryId ?? null }, Nothing);
+    }
+    /** A run's row, or null (`runs.get`). */
+    runGet(input) {
+        return this.call('runs.get', input, Run.nullable());
+    }
+    /** The door's one write: the receipt, the cursor (absent: left as it is)
+     *  and the work rows; `kept: false`, and nothing written, for a duplicate. */
+    keepDelivery(input) {
+        const { delivery, work } = input;
+        const params = {
+            subscriptionId: input.subscriptionId,
+            ...('checkpoint' in input ? { checkpoint: input.checkpoint } : {}),
+            delivery: { ...delivery, externalId: delivery.externalId ?? null, replayOf: delivery.replayOf ?? null },
+            work: work.map((row) => ({ ...row, dueAt: row.dueAt ?? null, teamId: row.teamId ?? null })),
+        };
+        return this.call('inbound.keepDelivery', params, zod_1.z.object({ kept: zod_1.z.boolean() }));
+    }
+    /** Kept deliveries, most recent first, without their events. */
+    deliveries(input) {
+        return this.call('inbound.deliveries', { subscriptionId: input.subscriptionId ?? null, since: input.since ?? null, limit: input.limit }, zod_1.z.array(Delivery));
+    }
+    /** One kept delivery with its events, or null. */
+    delivery(input) {
+        return this.call('inbound.delivery', input, Delivery.nullable());
+    }
+    /** Forget settled deliveries received before `before`: how many went. */
+    sweepDeliveries(input) {
+        return this.call('inbound.sweepDeliveries', input, zod_1.z.number());
+    }
+    /** A subscription's saved pull cursor (`inbound.checkpoint`). */
+    checkpoint(input) {
+        return this.call('inbound.checkpoint', input, zod_1.z.object({ checkpoint: zod_1.z.unknown() }).nullable());
     }
     /** An operator asks to cancel the run (the records contract's `requestCancel`). */
     async requestCancel(input) {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@listen-fire/engine",
   "license": "Apache-2.0",
-  "version": "0.12.0-rc.8",
+  "version": "0.12.0",
   "description": "The movement engine for this release's language and its host contract: the Rust engine's shim, the EngineHost families, the run host, the embed kit, and the adapter and model types they reach. Every shell (the hosted product, the `lf` command line, an embedder) runs the same engine. A run pinned to a release this one does not read is refused by name. Embedders reach it only through public/* (the exports map); the internals resolve only under the `movement-engine-internals` condition, which only test runners set",
   "engines": {
-    "node": "22.20.0"
+    "node": ">=22.23.4 <23"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -17,9 +17,9 @@
   "dependencies": {
     "safe-stable-stringify": "2.5.0",
     "zod": "4.1.12",
-    "@listen-fire/movement-lang": "^0.12.0-rc.8",
-    "@listen-fire/engine-contracts": "^0.12.0-rc.8",
-    "@listen-fire/module-runtime": "^0.12.0-rc.8"
+    "@listen-fire/module-runtime": "^0.12.0",
+    "@listen-fire/engine-contracts": "^0.12.0",
+    "@listen-fire/movement-lang": "^0.12.0"
   },
   "devDependencies": {
     "@types/jest": "29.5.14",
@@ -35,8 +35,7 @@
     "dist"
   ],
   "publishConfig": {
-    "access": "public",
-    "tag": "next"
+    "access": "public"
   },
   "scripts": {
     "code:type-check": "tsc --pretty --noEmit",