@shware/workflow 6.1.1 → 8.0.0

package/dist/engine/ports.d.cts

@@ -67,11 +67,15 @@ export interface FactSource {
    * How many times an event occurred. `sinceMs` bounds the window (within /
    * anchoring); `where` is a payload-only condition tree — count only events
    * whose payload matches (evaluate with matchesWhere from engine/condition).
+   * `atLeast` is the threshold the caller compares against: an implementation
+   * may stop counting there and return any number ≥ it, or ignore it and count
+   * them all.
    */
   countEvents(event: string, opts?: {
     sinceMs?: number;
     untilMs?: number;
     where?: ConditionIR;
+    atLeast?: number;
   }): Promise<number>;
   getProperty(path: string): Promise<ScalarIR | undefined>;
   /** Resolve a segment definition by id (stored with the bundle at deploy time). */
@@ -106,9 +110,12 @@ export interface OutboundMessage {
   /** Email and push: the template's subscription topic, null for a transactional message (absent for other channels). */
   topic?: string | null | undefined;
   /**
-   * `${instanceId}:${nodeId}` (plus `:${token}` for a push copy) — one per copy. Senders
-   * de-duplicate on it, making replays and retries safe, and it is the copy's identity for
-   * tracking: a push carries it in its payload, so the app can report the tap against it.
+   * `${instanceId}:${nodeId}` (plus `:${token}` for a push copy) — one per copy, stable across
+   * replays and retries. The engine skips a copy the observer reports settled
+   * (`messageSettled`); past that, de-duplication is the provider's: APNs (collapse id) and Web
+   * Push (`Topic`) collapse on it, SES and the Cloudflare REST API cannot, so a crash between the
+   * provider taking a copy and its report still sends it twice there. It is also the copy's
+   * identity for tracking: a push carries it in its payload, so the app can report the tap.
    */
   idempotencyKey: string;
   /** What the host's observer asked the sender to add for measuring this copy (see `MessageTracking`). */
@@ -185,6 +192,15 @@ export interface JourneyObserver {
     nodeId: string;
     at: number;
   }): Promise<void>;
+  /**
+   * Whether this copy (its idempotency key) was already settled — sent, or settled undelivered —
+   * by an earlier run of the same step. The send and its report sit inside one durable step, so
+   * an instance that crashes after both but before the step's checkpoint replays the step; a
+   * settled copy is then skipped instead of reaching the transport a second time. (A crash
+   * between the transport taking it and the report is still a second send: only a provider that
+   * de-duplicates on the key closes that.)
+   */
+  messageSettled?(message: OutboundMessage): Promise<boolean>;
   /** A copy is about to go out; the tracking returned travels with it to the sender. */
   messagePrepared?(message: OutboundMessage): Promise<MessageTracking | undefined>;
   /** The transport took the copy (`delivered: true`), or settled it undelivered; a thrown send is not reported. */
@@ -256,6 +272,8 @@ export interface JourneyContext {
    * Date.now() at run time.
    */
   enteredAtMs: number;
+  /** Who the instance belongs to now, for one that can change hands; `userId` otherwise. */
+  currentUserId?: (() => Promise<string>) | undefined;
   step: EngineStep;
   facts: FactSource;
   messages: MessageSender;

package/dist/engine/ports.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"ports.d.cts","names":[],"sources":["../../src/engine/ports.ts"],"mappings":";;;;;;;;;;;;;;;iBAiBiB;;EAEf,GAAG,GAAG,cAAc,UAAU,QAAQ,KAAK,QAAQ;;;;;EAMnD,MAAM,cAAc,aAAa;;;;;;;;;;;;;;;EAgBjC,UACE,cACA,2BACA;IAAY;MACX;;EAGH,YAAY,eAAe;;;;;;;;;;;;EAa3B,YACE,cACA;IAAQ;IAAmB;MAC1B;;;iBAIY;EACf;EACA;;;iBAIe;;;;;;EAMf,YACE,eACA;IAAS;IAAkB;IAAkB,QAAQ;MACpD;EACH,YAAY,eAAe,QAAQ;;EAEnC,oBAAoB,eAAe,QAAQ;;EAE3C,eAAe,QAAQ;;;;;;EAMvB,cAAc,SAAS,WAAW,iBAAiB;;iBAGpC;;EAEf;EACA;EACA;EACA,SAAS;EACT;;EAEA,OAAO,eAAe;EACtB;;;;;;EAMA;;EAEA,SAAS;;EAET;;;;;;EAMA;;EAEA,WAAW;;;YAID;;;;;;iBAOK;;;;;;EAMf;;;;;EAKA,QAAQ,aAAa,SAAS;;EAE9B;;;;;;EAMA;;EAEA,OAAO;;;;;;EAMP,eAAe;;;;;;;iBAQA;EACf;EACA;;iBAGe;EACf,KAAK,SAAS,kBAAkB,eAAe;;;;;;;;;iBAUhC;;EAEf,SAAS;IACP;IACA;IACA;IACA;MACE;;EAEJ,aAAa;IACX;IACA;IACA;IACA;IACA;MACE;;EAEJ,iBAAiB,SAAS,kBAAkB,QAAQ;;EAEpD,aAAa,SAAS,iBAAiB;IAAU;MAAoB,aAAa;;EAElF,UAAU;IACR;IACA;IACA;IACA,QAAQ;IACR;;IAEA;MACE;;;;;;;;;iBAUW;EACf,SAAS;IACP,SAAS;IACT;IACA,OAAO,eAAe;MACpB,eAAe;;;iBAIJ;;;;;;;;EAQf,KAAK,eAAe,SAAS,eAAe,uBAAuB,aAAa;;;iBAIjE;;EAEf;;EAEA,MAAM,eAAe;EACrB;;EAEA;;;;;;;iBAQe;EACf,OAAO,YAAY,mBAAmB;;iBAGvB;EACf;;EAEA;;;;;;;EAOA;EACA,MAAM;EACN,OAAO;EACP,UAAU;EACV,QAAQ;;EAER,UAAU;;EAEV,YAAY;;EAEZ,WAAW;;;;;;;YAQD;EACN;;EACA;EAAkB;;EAClB;;EACA;;EACA"}
+{"version":3,"file":"ports.d.cts","names":[],"sources":["../../src/engine/ports.ts"],"mappings":";;;;;;;;;;;;;;;iBAiBiB;;EAEf,GAAG,GAAG,cAAc,UAAU,QAAQ,KAAK,QAAQ;;;;;EAMnD,MAAM,cAAc,aAAa;;;;;;;;;;;;;;;EAgBjC,UACE,cACA,2BACA;IAAY;MACX;;EAGH,YAAY,eAAe;;;;;;;;;;;;EAa3B,YACE,cACA;IAAQ;IAAmB;MAC1B;;;iBAIY;EACf;EACA;;;iBAIe;;;;;;;;;EASf,YACE,eACA;IAAS;IAAkB;IAAkB,QAAQ;IAAa;MACjE;EACH,YAAY,eAAe,QAAQ;;EAEnC,oBAAoB,eAAe,QAAQ;;EAE3C,eAAe,QAAQ;;;;;;EAMvB,cAAc,SAAS,WAAW,iBAAiB;;iBAGpC;;EAEf;EACA;EACA;EACA,SAAS;EACT;;EAEA,OAAO,eAAe;EACtB;;;;;;EAMA;;EAEA,SAAS;;EAET;;;;;;;;;EASA;;EAEA,WAAW;;;YAID;;;;;;iBAOK;;;;;;EAMf;;;;;EAKA,QAAQ,aAAa,SAAS;;EAE9B;;;;;;EAMA;;EAEA,OAAO;;;;;;EAMP,eAAe;;;;;;;iBAQA;EACf;EACA;;iBAGe;EACf,KAAK,SAAS,kBAAkB,eAAe;;;;;;;;;iBAUhC;;EAEf,SAAS;IACP;IACA;IACA;IACA;MACE;;EAEJ,aAAa;IACX;IACA;IACA;IACA;IACA;MACE;;;;;;;;;EASJ,gBAAgB,SAAS,kBAAkB;;EAE3C,iBAAiB,SAAS,kBAAkB,QAAQ;;EAEpD,aAAa,SAAS,iBAAiB;IAAU;MAAoB,aAAa;;EAElF,UAAU;IACR;IACA;IACA;IACA,QAAQ;IACR;;IAEA;MACE;;;;;;;;;iBAUW;EACf,SAAS;IACP,SAAS;IACT;IACA,OAAO,eAAe;MACpB,eAAe;;;iBAIJ;;;;;;;;EAQf,KAAK,eAAe,SAAS,eAAe,uBAAuB,aAAa;;;iBAIjE;;EAEf;;EAEA,MAAM,eAAe;EACrB;;EAEA;;;;;;;iBAQe;EACf,OAAO,YAAY,mBAAmB;;iBAGvB;EACf;;EAEA;;;;;;;EAOA;;EAEA,uBAAuB;EACvB,MAAM;EACN,OAAO;EACP,UAAU;EACV,QAAQ;;EAER,UAAU;;EAEV,YAAY;;EAEZ,WAAW;;;;;;;YAQD;EACN;;EACA;EAAkB;;EAClB;;EACA;;EACA"}

package/dist/engine/ports.d.mts

@@ -67,11 +67,15 @@ export interface FactSource {
    * How many times an event occurred. `sinceMs` bounds the window (within /
    * anchoring); `where` is a payload-only condition tree — count only events
    * whose payload matches (evaluate with matchesWhere from engine/condition).
+   * `atLeast` is the threshold the caller compares against: an implementation
+   * may stop counting there and return any number ≥ it, or ignore it and count
+   * them all.
    */
   countEvents(event: string, opts?: {
     sinceMs?: number;
     untilMs?: number;
     where?: ConditionIR;
+    atLeast?: number;
   }): Promise<number>;
   getProperty(path: string): Promise<ScalarIR | undefined>;
   /** Resolve a segment definition by id (stored with the bundle at deploy time). */
@@ -106,9 +110,12 @@ export interface OutboundMessage {
   /** Email and push: the template's subscription topic, null for a transactional message (absent for other channels). */
   topic?: string | null | undefined;
   /**
-   * `${instanceId}:${nodeId}` (plus `:${token}` for a push copy) — one per copy. Senders
-   * de-duplicate on it, making replays and retries safe, and it is the copy's identity for
-   * tracking: a push carries it in its payload, so the app can report the tap against it.
+   * `${instanceId}:${nodeId}` (plus `:${token}` for a push copy) — one per copy, stable across
+   * replays and retries. The engine skips a copy the observer reports settled
+   * (`messageSettled`); past that, de-duplication is the provider's: APNs (collapse id) and Web
+   * Push (`Topic`) collapse on it, SES and the Cloudflare REST API cannot, so a crash between the
+   * provider taking a copy and its report still sends it twice there. It is also the copy's
+   * identity for tracking: a push carries it in its payload, so the app can report the tap.
    */
   idempotencyKey: string;
   /** What the host's observer asked the sender to add for measuring this copy (see `MessageTracking`). */
@@ -185,6 +192,15 @@ export interface JourneyObserver {
     nodeId: string;
     at: number;
   }): Promise<void>;
+  /**
+   * Whether this copy (its idempotency key) was already settled — sent, or settled undelivered —
+   * by an earlier run of the same step. The send and its report sit inside one durable step, so
+   * an instance that crashes after both but before the step's checkpoint replays the step; a
+   * settled copy is then skipped instead of reaching the transport a second time. (A crash
+   * between the transport taking it and the report is still a second send: only a provider that
+   * de-duplicates on the key closes that.)
+   */
+  messageSettled?(message: OutboundMessage): Promise<boolean>;
   /** A copy is about to go out; the tracking returned travels with it to the sender. */
   messagePrepared?(message: OutboundMessage): Promise<MessageTracking | undefined>;
   /** The transport took the copy (`delivered: true`), or settled it undelivered; a thrown send is not reported. */
@@ -256,6 +272,8 @@ export interface JourneyContext {
    * Date.now() at run time.
    */
   enteredAtMs: number;
+  /** Who the instance belongs to now, for one that can change hands; `userId` otherwise. */
+  currentUserId?: (() => Promise<string>) | undefined;
   step: EngineStep;
   facts: FactSource;
   messages: MessageSender;

package/dist/engine/ports.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ports.d.mts","names":[],"sources":["../../src/engine/ports.ts"],"mappings":";;;;;;;;;;;;;;;iBAiBiB;;EAEf,GAAG,GAAG,cAAc,UAAU,QAAQ,KAAK,QAAQ;;;;;EAMnD,MAAM,cAAc,aAAa;;;;;;;;;;;;;;;EAgBjC,UACE,cACA,2BACA;IAAY;MACX;;EAGH,YAAY,eAAe;;;;;;;;;;;;EAa3B,YACE,cACA;IAAQ;IAAmB;MAC1B;;;iBAIY;EACf;EACA;;;iBAIe;;;;;;EAMf,YACE,eACA;IAAS;IAAkB;IAAkB,QAAQ;MACpD;EACH,YAAY,eAAe,QAAQ;;EAEnC,oBAAoB,eAAe,QAAQ;;EAE3C,eAAe,QAAQ;;;;;;EAMvB,cAAc,SAAS,WAAW,iBAAiB;;iBAGpC;;EAEf;EACA;EACA;EACA,SAAS;EACT;;EAEA,OAAO,eAAe;EACtB;;;;;;EAMA;;EAEA,SAAS;;EAET;;;;;;EAMA;;EAEA,WAAW;;;YAID;;;;;;iBAOK;;;;;;EAMf;;;;;EAKA,QAAQ,aAAa,SAAS;;EAE9B;;;;;;EAMA;;EAEA,OAAO;;;;;;EAMP,eAAe;;;;;;;iBAQA;EACf;EACA;;iBAGe;EACf,KAAK,SAAS,kBAAkB,eAAe;;;;;;;;;iBAUhC;;EAEf,SAAS;IACP;IACA;IACA;IACA;MACE;;EAEJ,aAAa;IACX;IACA;IACA;IACA;IACA;MACE;;EAEJ,iBAAiB,SAAS,kBAAkB,QAAQ;;EAEpD,aAAa,SAAS,iBAAiB;IAAU;MAAoB,aAAa;;EAElF,UAAU;IACR;IACA;IACA;IACA,QAAQ;IACR;;IAEA;MACE;;;;;;;;;iBAUW;EACf,SAAS;IACP,SAAS;IACT;IACA,OAAO,eAAe;MACpB,eAAe;;;iBAIJ;;;;;;;;EAQf,KAAK,eAAe,SAAS,eAAe,uBAAuB,aAAa;;;iBAIjE;;EAEf;;EAEA,MAAM,eAAe;EACrB;;EAEA;;;;;;;iBAQe;EACf,OAAO,YAAY,mBAAmB;;iBAGvB;EACf;;EAEA;;;;;;;EAOA;EACA,MAAM;EACN,OAAO;EACP,UAAU;EACV,QAAQ;;EAER,UAAU;;EAEV,YAAY;;EAEZ,WAAW;;;;;;;YAQD;EACN;;EACA;EAAkB;;EAClB;;EACA;;EACA"}
+{"version":3,"file":"ports.d.mts","names":[],"sources":["../../src/engine/ports.ts"],"mappings":";;;;;;;;;;;;;;;iBAiBiB;;EAEf,GAAG,GAAG,cAAc,UAAU,QAAQ,KAAK,QAAQ;;;;;EAMnD,MAAM,cAAc,aAAa;;;;;;;;;;;;;;;EAgBjC,UACE,cACA,2BACA;IAAY;MACX;;EAGH,YAAY,eAAe;;;;;;;;;;;;EAa3B,YACE,cACA;IAAQ;IAAmB;MAC1B;;;iBAIY;EACf;EACA;;;iBAIe;;;;;;;;;EASf,YACE,eACA;IAAS;IAAkB;IAAkB,QAAQ;IAAa;MACjE;EACH,YAAY,eAAe,QAAQ;;EAEnC,oBAAoB,eAAe,QAAQ;;EAE3C,eAAe,QAAQ;;;;;;EAMvB,cAAc,SAAS,WAAW,iBAAiB;;iBAGpC;;EAEf;EACA;EACA;EACA,SAAS;EACT;;EAEA,OAAO,eAAe;EACtB;;;;;;EAMA;;EAEA,SAAS;;EAET;;;;;;;;;EASA;;EAEA,WAAW;;;YAID;;;;;;iBAOK;;;;;;EAMf;;;;;EAKA,QAAQ,aAAa,SAAS;;EAE9B;;;;;;EAMA;;EAEA,OAAO;;;;;;EAMP,eAAe;;;;;;;iBAQA;EACf;EACA;;iBAGe;EACf,KAAK,SAAS,kBAAkB,eAAe;;;;;;;;;iBAUhC;;EAEf,SAAS;IACP;IACA;IACA;IACA;MACE;;EAEJ,aAAa;IACX;IACA;IACA;IACA;IACA;MACE;;;;;;;;;EASJ,gBAAgB,SAAS,kBAAkB;;EAE3C,iBAAiB,SAAS,kBAAkB,QAAQ;;EAEpD,aAAa,SAAS,iBAAiB;IAAU;MAAoB,aAAa;;EAElF,UAAU;IACR;IACA;IACA;IACA,QAAQ;IACR;;IAEA;MACE;;;;;;;;;iBAUW;EACf,SAAS;IACP,SAAS;IACT;IACA,OAAO,eAAe;MACpB,eAAe;;;iBAIJ;;;;;;;;EAQf,KAAK,eAAe,SAAS,eAAe,uBAAuB,aAAa;;;iBAIjE;;EAEf;;EAEA,MAAM,eAAe;EACrB;;EAEA;;;;;;;iBAQe;EACf,OAAO,YAAY,mBAAmB;;iBAGvB;EACf;;EAEA;;;;;;;EAOA;;EAEA,uBAAuB;EACvB,MAAM;EACN,OAAO;EACP,UAAU;EACV,QAAQ;;EAER,UAAU;;EAEV,YAAY;;EAEZ,WAAW;;;;;;;YAQD;EACN;;EACA;EAAkB;;EAClB;;EACA;;EACA"}

package/dist/host/batch.cjs

@@ -0,0 +1,172 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_store_erasure = require("../store/erasure.cjs");
+const require_store_identity = require("../store/identity.cjs");
+require("../store/index.cjs");
+const require_host_ingest = require("./ingest.cjs");
+const require_contract = require("../contract.cjs");
+// src/host/batch.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.length > 0;
+}
+/** A profile value: a scalar or null (which removes the property). Nested values are not profile data. */
+function isScalarOrNull(value) {
+	return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+/** How far ahead of the server's clock an event or device `ts` may be: clock skew, not the future. */
+const TS_FUTURE_TOLERANCE_MS = 3e5;
+const TS_ERROR = "ts must be a non-negative integer no later than 5 minutes in the future";
+/**
+* A caller's timestamp: epoch milliseconds, whole, not negative, and not past the skew tolerance.
+* A far-future ts would put the event ahead of everything a window condition reads, and a
+* fractional or unsafe one does not survive the store.
+*/
+function isValidTs(ts) {
+	return typeof ts === "number" && Number.isSafeInteger(ts) && ts >= 0 && ts <= Date.now() + TS_FUTURE_TOLERANCE_MS;
+}
+/** What is wrong with an untrusted identity: at least one id, and a user id outside the visitors' prefix. */
+function identityError(userId, visitorId) {
+	if (userId === void 0 && visitorId === void 0) return "userId or visitorId required";
+	if (userId !== void 0 && !isNonEmptyString(userId)) return "userId must be a non-empty string";
+	if (typeof userId === "string" && require_store_identity.isVisitorSubject(userId)) return "userId must not start with 'visitor:'";
+	if (visitorId !== void 0 && !isNonEmptyString(visitorId)) return "visitorId must be a non-empty string";
+}
+/**
+* An untrusted batch, checked whole: one bad part refuses all of it, so a producer never has half
+* a report applied. Contract `mode: 'report'` logs what it would refuse and keeps the original.
+*/
+function parseBatch(raw, validation) {
+	const refuse = (error) => ({
+		ok: false,
+		error
+	});
+	if (!isPlainObject(raw)) return refuse("batch must be an object");
+	const { userId, visitorId, profile, at, events } = raw;
+	const identity = identityError(userId, visitorId);
+	if (identity !== void 0) return refuse(identity);
+	if (at !== void 0 && !isValidTs(at)) return refuse(`at: ${TS_ERROR}`);
+	if (profile === void 0 && events === void 0) return refuse("profile or events required");
+	const batch = {
+		...userId === void 0 ? {} : { userId },
+		...visitorId === void 0 ? {} : { visitorId },
+		...at === void 0 ? {} : { at }
+	};
+	const contract = validation.contract;
+	const report = (what, issues) => console.warn(`[workflow] contract would refuse ${what}: ${issues.map((i) => `${i.path || "(root)"}: ${i.message}`).join("; ")}`);
+	if (profile !== void 0) {
+		if (!isPlainObject(profile)) return refuse("profile must be an object");
+		if (!Object.values(profile).every(isScalarOrNull)) return refuse("profile values must be scalars (string, number, boolean) or null");
+		batch.profile = profile;
+		if (contract !== void 0) {
+			const result = contract.parseProfilePatch(profile);
+			if (result.ok) batch.profile = result.data;
+			else if (validation.mode === "report") report("the profile", result.issues);
+			else return {
+				ok: false,
+				error: "profile refused by the contract",
+				issues: result.issues
+			};
+		}
+	}
+	if (events !== void 0) {
+		if (!Array.isArray(events)) return refuse("events must be an array");
+		const parsed = [];
+		for (const item of events) {
+			if (!isPlainObject(item)) return refuse("every event must be an object");
+			const { event, payload, id, ts } = item;
+			if (!isNonEmptyString(event)) return refuse("every event needs a name");
+			if (event.startsWith("$")) return refuse("event names starting with $ are reserved");
+			if (id !== void 0 && !isNonEmptyString(id)) return refuse("an event id must be a non-empty string");
+			if (ts !== void 0 && !isValidTs(ts)) return refuse(TS_ERROR);
+			if (payload !== void 0 && !isPlainObject(payload)) return refuse("payload must be an object");
+			let accepted = payload;
+			if (contract !== void 0) {
+				const result = require_contract.checkEvent(contract, event, payload ?? {});
+				const what = `event '${event}'${id === void 0 ? "" : ` (${id})`}`;
+				if (result.ok) accepted = result.data;
+				else if (validation.mode === "report") report(what, result.issues);
+				else return {
+					ok: false,
+					error: `${what} refused by the contract`,
+					issues: result.issues
+				};
+			}
+			parsed.push({
+				event,
+				payload: accepted,
+				id,
+				ts
+			});
+		}
+		batch.events = parsed;
+	}
+	return {
+		ok: true,
+		batch
+	};
+}
+/**
+* Apply a checked batch: the visitor's merge, the profile, then each event in order. Every part is idempotent (a
+* property older than the stored one is skipped, an event id is stored once), so a caller retries
+* a failed batch whole.
+*/
+async function ingestBatch(env, batch, store) {
+	const { userId, visitorId, profile, at, events = [] } = batch;
+	if (userId !== void 0 && visitorId !== void 0) await require_host_ingest.linkVisitor(env, visitorId, userId, store, at);
+	const subject = userId ?? await store.touchVisitor(visitorId ?? "", at ?? Date.now());
+	const result = { events: [] };
+	if (profile !== void 0) result.profile = await require_host_ingest.identifyUser(env, subject, profile, store, at);
+	for (const { event, payload, id, ts } of events) result.events.push(await require_host_ingest.ingestEvent(env, {
+		userId: subject,
+		event,
+		payload,
+		id,
+		ts
+	}, store));
+	return result;
+}
+/** First retry after 30 s, doubling up to 15 minutes. */
+function retryDelay(attempts) {
+	return Math.min(30 * 2 ** Math.max(attempts - 1, 0), 900);
+}
+/**
+* Consume delivered batches one at a time. A batch that can never succeed is acknowledged, not
+* retried: one the contract refuses (logged with the field paths, never the payload) and one for
+* an erased user. Anything else is retried with a backoff until the queue's `max_retries` hands
+* it to its dead letter queue.
+*/
+async function consumeBatches(env, messages, store, validation) {
+	for (const message of messages) {
+		const parsed = parseBatch(message.body, validation);
+		if (!parsed.ok) {
+			const issues = parsed.issues?.map((i) => `${i.path || "(root)"}: ${i.message}`).join("; ");
+			console.error(`[workflow queue] batch ${message.id} refused: ${parsed.error}${issues ? ` (${issues})` : ""}`);
+			message.ack();
+			continue;
+		}
+		try {
+			await ingestBatch(env, parsed.batch, store);
+			message.ack();
+		} catch (error) {
+			if (error instanceof require_store_erasure.UserErasedError) {
+				message.ack();
+				continue;
+			}
+			console.error(`[workflow queue] batch ${message.id} failed`, error);
+			message.retry({ delaySeconds: retryDelay(message.attempts) });
+		}
+	}
+}
+exports.TS_ERROR = TS_ERROR;
+exports.consumeBatches = consumeBatches;
+exports.identityError = identityError;
+exports.ingestBatch = ingestBatch;
+exports.isNonEmptyString = isNonEmptyString;
+exports.isPlainObject = isPlainObject;
+exports.isScalarOrNull = isScalarOrNull;
+exports.isValidTs = isValidTs;
+exports.parseBatch = parseBatch;
+
+//# sourceMappingURL=batch.cjs.map

package/dist/host/batch.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.cjs","names":["isVisitorSubject","checkEvent","linkVisitor","identifyUser","ingestEvent","UserErasedError"],"sources":["../../src/host/batch.ts"],"sourcesContent":["import { checkEvent } from '../contract';\nimport {\n  type JourneyStore,\n  type ProfileProps,\n  UserErasedError,\n  isVisitorSubject,\n} from '../store/index';\nimport type { IngestValidation } from './http';\nimport {\n  type IdentifyResult,\n  type IngestResult,\n  identifyUser,\n  ingestEvent,\n  linkVisitor,\n} from './ingest';\nimport type { JourneyEnv } from './platform';\n\n/**\n * One producer report as a single unit: what the user's profile now says and what they just did.\n * The profile is merged before the first event, so a journey an event starts always finds the\n * recipient that report knew about, whichever transport carried it and whatever arrived around\n * it. The same shape travels over HTTP (`POST /ingest`) and through a queue.\n */\nexport interface JourneyBatch {\n  /** The signed-in user. With `visitorId` too, that visitor is this user: they merge, once. */\n  userId?: string | undefined;\n  /** The visitor before sign-in: a stable id for one client, renewed when a user signs out. */\n  visitorId?: string | undefined;\n  profile?: ProfileProps | undefined;\n  /**\n   * When the profile was read (epoch ms), the Worker's clock when omitted. A property written\n   * later stays: a redelivered batch cannot put an old address back.\n   */\n  at?: number | undefined;\n  events?: readonly BatchEvent[] | undefined;\n}\n\nexport interface BatchEvent {\n  event: string;\n  payload?: Record<string, unknown> | undefined;\n  /** The occurrence's identity: a redelivered batch records it once. */\n  id?: string | undefined;\n  ts?: number | undefined;\n}\n\nexport interface BatchResult {\n  profile?: IdentifyResult;\n  events: IngestResult[];\n}\n\nexport function isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nexport function isNonEmptyString(value: unknown): value is string {\n  return typeof value === 'string' && value.length > 0;\n}\n\n/** A profile value: a scalar or null (which removes the property). Nested values are not profile data. */\nexport function isScalarOrNull(value: unknown): value is string | number | boolean | null {\n  return (\n    value === null ||\n    typeof value === 'string' ||\n    typeof value === 'number' ||\n    typeof value === 'boolean'\n  );\n}\n\n/** How far ahead of the server's clock an event or device `ts` may be: clock skew, not the future. */\nconst TS_FUTURE_TOLERANCE_MS = 5 * 60_000;\nexport const TS_ERROR = 'ts must be a non-negative integer no later than 5 minutes in the future';\n\n/**\n * A caller's timestamp: epoch milliseconds, whole, not negative, and not past the skew tolerance.\n * A far-future ts would put the event ahead of everything a window condition reads, and a\n * fractional or unsafe one does not survive the store.\n */\nexport function isValidTs(ts: unknown): ts is number {\n  return (\n    typeof ts === 'number' &&\n    Number.isSafeInteger(ts) &&\n    ts >= 0 &&\n    ts <= Date.now() + TS_FUTURE_TOLERANCE_MS\n  );\n}\n\n/** What is wrong with an untrusted identity: at least one id, and a user id outside the visitors' prefix. */\nexport function identityError(userId: unknown, visitorId: unknown): string | undefined {\n  if (userId === undefined && visitorId === undefined) return 'userId or visitorId required';\n  if (userId !== undefined && !isNonEmptyString(userId)) {\n    return 'userId must be a non-empty string';\n  }\n  if (typeof userId === 'string' && isVisitorSubject(userId)) {\n    return \"userId must not start with 'visitor:'\";\n  }\n  if (visitorId !== undefined && !isNonEmptyString(visitorId)) {\n    return 'visitorId must be a non-empty string';\n  }\n  return undefined;\n}\n\nexport type ParsedBatch =\n  | { ok: true; batch: JourneyBatch }\n  | { ok: false; error: string; issues?: readonly { path: string; message: string }[] };\n\n/**\n * An untrusted batch, checked whole: one bad part refuses all of it, so a producer never has half\n * a report applied. Contract `mode: 'report'` logs what it would refuse and keeps the original.\n */\nexport function parseBatch(raw: unknown, validation: IngestValidation): ParsedBatch {\n  const refuse = (error: string): ParsedBatch => ({ ok: false, error });\n  if (!isPlainObject(raw)) return refuse('batch must be an object');\n  const { userId, visitorId, profile, at, events } = raw;\n  const identity = identityError(userId, visitorId);\n  if (identity !== undefined) return refuse(identity);\n  if (at !== undefined && !isValidTs(at)) return refuse(`at: ${TS_ERROR}`);\n  if (profile === undefined && events === undefined) return refuse('profile or events required');\n\n  const batch: JourneyBatch = {\n    ...(userId === undefined ? {} : { userId: userId as string }),\n    ...(visitorId === undefined ? {} : { visitorId: visitorId as string }),\n    ...(at === undefined ? {} : { at }),\n  };\n  const contract = validation.contract;\n  const report = (what: string, issues: readonly { path: string; message: string }[]) =>\n    console.warn(\n      `[workflow] contract would refuse ${what}: ${issues\n        .map((i) => `${i.path || '(root)'}: ${i.message}`)\n        .join('; ')}`\n    );\n\n  if (profile !== undefined) {\n    if (!isPlainObject(profile)) return refuse('profile must be an object');\n    if (!Object.values(profile).every(isScalarOrNull)) {\n      return refuse('profile values must be scalars (string, number, boolean) or null');\n    }\n    batch.profile = profile as ProfileProps;\n    if (contract !== undefined) {\n      const result = contract.parseProfilePatch(profile);\n      if (result.ok) batch.profile = result.data as ProfileProps;\n      else if (validation.mode === 'report') report('the profile', result.issues);\n      else return { ok: false, error: 'profile refused by the contract', issues: result.issues };\n    }\n  }\n\n  if (events !== undefined) {\n    if (!Array.isArray(events)) return refuse('events must be an array');\n    const parsed: BatchEvent[] = [];\n    for (const item of events as unknown[]) {\n      if (!isPlainObject(item)) return refuse('every event must be an object');\n      const { event, payload, id, ts } = item;\n      if (!isNonEmptyString(event)) return refuse('every event needs a name');\n      if (event.startsWith('$')) return refuse('event names starting with $ are reserved');\n      if (id !== undefined && !isNonEmptyString(id)) {\n        return refuse('an event id must be a non-empty string');\n      }\n      if (ts !== undefined && !isValidTs(ts)) return refuse(TS_ERROR);\n      if (payload !== undefined && !isPlainObject(payload)) {\n        return refuse('payload must be an object');\n      }\n      let accepted = payload;\n      if (contract !== undefined) {\n        const result = checkEvent(contract, event, payload ?? {});\n        const what = `event '${event}'${id === undefined ? '' : ` (${id})`}`;\n        if (result.ok) accepted = result.data;\n        else if (validation.mode === 'report') report(what, result.issues);\n        else return { ok: false, error: `${what} refused by the contract`, issues: result.issues };\n      }\n      parsed.push({ event, payload: accepted, id, ts });\n    }\n    batch.events = parsed;\n  }\n  return { ok: true, batch };\n}\n\n/**\n * Apply a checked batch: the visitor's merge, the profile, then each event in order. Every part is idempotent (a\n * property older than the stored one is skipped, an event id is stored once), so a caller retries\n * a failed batch whole.\n */\nexport async function ingestBatch(\n  env: JourneyEnv,\n  batch: JourneyBatch,\n  store: JourneyStore\n): Promise<BatchResult> {\n  const { userId, visitorId, profile, at, events = [] } = batch;\n  if (userId !== undefined && visitorId !== undefined) {\n    await linkVisitor(env, visitorId, userId, store, at);\n  }\n  // A late report of a visitor who has signed in since reaches the user\n  const subject = userId ?? (await store.touchVisitor(visitorId ?? '', at ?? Date.now()));\n  const result: BatchResult = { events: [] };\n  if (profile !== undefined) result.profile = await identifyUser(env, subject, profile, store, at);\n  for (const { event, payload, id, ts } of events) {\n    result.events.push(await ingestEvent(env, { userId: subject, event, payload, id, ts }, store));\n  }\n  return result;\n}\n\n/** A delivered queue message (the subset of the Cloudflare Queues `Message` used). */\nexport interface QueueMessageLike {\n  id: string;\n  body: unknown;\n  /** Delivery attempts so far, this one included. */\n  attempts: number;\n  ack(): void;\n  retry(options?: { delaySeconds?: number }): void;\n}\n\n/** First retry after 30 s, doubling up to 15 minutes. */\nfunction retryDelay(attempts: number): number {\n  return Math.min(30 * 2 ** Math.max(attempts - 1, 0), 900);\n}\n\n/**\n * Consume delivered batches one at a time. A batch that can never succeed is acknowledged, not\n * retried: one the contract refuses (logged with the field paths, never the payload) and one for\n * an erased user. Anything else is retried with a backoff until the queue's `max_retries` hands\n * it to its dead letter queue.\n */\nexport async function consumeBatches(\n  env: JourneyEnv,\n  messages: readonly QueueMessageLike[],\n  store: JourneyStore,\n  validation: IngestValidation\n): Promise<void> {\n  for (const message of messages) {\n    const parsed = parseBatch(message.body, validation);\n    if (!parsed.ok) {\n      const issues = parsed.issues?.map((i) => `${i.path || '(root)'}: ${i.message}`).join('; ');\n      console.error(\n        `[workflow queue] batch ${message.id} refused: ${parsed.error}${issues ? ` (${issues})` : ''}`\n      );\n      message.ack();\n      continue;\n    }\n    try {\n      await ingestBatch(env, parsed.batch, store);\n      message.ack();\n    } catch (error) {\n      if (error instanceof UserErasedError) {\n        message.ack();\n        continue;\n      }\n      console.error(`[workflow queue] batch ${message.id} failed`, error);\n      message.retry({ delaySeconds: retryDelay(message.attempts) });\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/host/batch.d.cts

@@ -0,0 +1,88 @@
+import { JourneyStore, ProfileProps } from "../store/index.cjs";
+import { JourneyEnv } from "./platform.cjs";
+import { IdentifyResult, IngestResult } from "./ingest.cjs";
+import { IngestValidation } from "./http.cjs";
+/**
+ * One producer report as a single unit: what the user's profile now says and what they just did.
+ * The profile is merged before the first event, so a journey an event starts always finds the
+ * recipient that report knew about, whichever transport carried it and whatever arrived around
+ * it. The same shape travels over HTTP (`POST /ingest`) and through a queue.
+ */
+export interface JourneyBatch {
+  /** The signed-in user. With `visitorId` too, that visitor is this user: they merge, once. */
+  userId?: string | undefined;
+  /** The visitor before sign-in: a stable id for one client, renewed when a user signs out. */
+  visitorId?: string | undefined;
+  profile?: ProfileProps | undefined;
+  /**
+   * When the profile was read (epoch ms), the Worker's clock when omitted. A property written
+   * later stays: a redelivered batch cannot put an old address back.
+   */
+  at?: number | undefined;
+  events?: readonly BatchEvent[] | undefined;
+}
+export interface BatchEvent {
+  event: string;
+  payload?: Record<string, unknown> | undefined;
+  /** The occurrence's identity: a redelivered batch records it once. */
+  id?: string | undefined;
+  ts?: number | undefined;
+}
+export interface BatchResult {
+  profile?: IdentifyResult;
+  events: IngestResult[];
+}
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function isNonEmptyString(value: unknown): value is string;
+/** A profile value: a scalar or null (which removes the property). Nested values are not profile data. */
+export declare function isScalarOrNull(value: unknown): value is string | number | boolean | null;
+export declare const TS_ERROR = "ts must be a non-negative integer no later than 5 minutes in the future";
+/**
+ * A caller's timestamp: epoch milliseconds, whole, not negative, and not past the skew tolerance.
+ * A far-future ts would put the event ahead of everything a window condition reads, and a
+ * fractional or unsafe one does not survive the store.
+ */
+export declare function isValidTs(ts: unknown): ts is number;
+/** What is wrong with an untrusted identity: at least one id, and a user id outside the visitors' prefix. */
+export declare function identityError(userId: unknown, visitorId: unknown): string | undefined;
+export type ParsedBatch = {
+  ok: true;
+  batch: JourneyBatch;
+} | {
+  ok: false;
+  error: string;
+  issues?: readonly {
+    path: string;
+    message: string;
+  }[];
+};
+/**
+ * An untrusted batch, checked whole: one bad part refuses all of it, so a producer never has half
+ * a report applied. Contract `mode: 'report'` logs what it would refuse and keeps the original.
+ */
+export declare function parseBatch(raw: unknown, validation: IngestValidation): ParsedBatch;
+/**
+ * Apply a checked batch: the visitor's merge, the profile, then each event in order. Every part is idempotent (a
+ * property older than the stored one is skipped, an event id is stored once), so a caller retries
+ * a failed batch whole.
+ */
+export declare function ingestBatch(env: JourneyEnv, batch: JourneyBatch, store: JourneyStore): Promise<BatchResult>;
+/** A delivered queue message (the subset of the Cloudflare Queues `Message` used). */
+export interface QueueMessageLike {
+  id: string;
+  body: unknown;
+  /** Delivery attempts so far, this one included. */
+  attempts: number;
+  ack(): void;
+  retry(options?: {
+    delaySeconds?: number;
+  }): void;
+}
+/**
+ * Consume delivered batches one at a time. A batch that can never succeed is acknowledged, not
+ * retried: one the contract refuses (logged with the field paths, never the payload) and one for
+ * an erased user. Anything else is retried with a backoff until the queue's `max_retries` hands
+ * it to its dead letter queue.
+ */
+export declare function consumeBatches(env: JourneyEnv, messages: readonly QueueMessageLike[], store: JourneyStore, validation: IngestValidation): Promise<void>;
+//# sourceMappingURL=batch.d.cts.map

package/dist/host/batch.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.cts","names":[],"sources":["../../src/host/batch.ts"],"mappings":";;;;;;;;;;iBAuBiB;;EAEf;;EAEA;EACA,UAAU;;;;;EAKV;EACA,kBAAkB;;iBAGH;EACf;EACA,UAAU;;EAEV;EACA;;iBAGe;EACf,UAAU;EACV,QAAQ;;wBAGM,cAAc,iBAAiB,SAAS;wBAIxC,iBAAiB,iBAAiB;;wBAKlC,eAAe,iBAAiB;qBAWnC;;;;;;wBAOG,UAAU,cAAc;;wBAUxB,cAAc,iBAAiB;YAcnC;EACN;EAAU,OAAO;;EACjB;EAAW;EAAe;IAAoB;IAAc;;;;;;;wBAMlD,WAAW,cAAc,YAAY,mBAAmB;;;;;;wBAuElD,YACpB,KAAK,YACL,OAAO,cACP,OAAO,eACN,QAAQ;;iBAgBM;EACf;EACA;;EAEA;EACA;EACA,MAAM;IAAY;;;;;;;;;wBAcE,eACpB,KAAK,YACL,mBAAmB,oBACnB,OAAO,cACP,YAAY,mBACX"}

package/dist/host/batch.d.mts

@@ -0,0 +1,88 @@
+import { JourneyStore, ProfileProps } from "../store/index.mjs";
+import { JourneyEnv } from "./platform.mjs";
+import { IdentifyResult, IngestResult } from "./ingest.mjs";
+import { IngestValidation } from "./http.mjs";
+/**
+ * One producer report as a single unit: what the user's profile now says and what they just did.
+ * The profile is merged before the first event, so a journey an event starts always finds the
+ * recipient that report knew about, whichever transport carried it and whatever arrived around
+ * it. The same shape travels over HTTP (`POST /ingest`) and through a queue.
+ */
+export interface JourneyBatch {
+  /** The signed-in user. With `visitorId` too, that visitor is this user: they merge, once. */
+  userId?: string | undefined;
+  /** The visitor before sign-in: a stable id for one client, renewed when a user signs out. */
+  visitorId?: string | undefined;
+  profile?: ProfileProps | undefined;
+  /**
+   * When the profile was read (epoch ms), the Worker's clock when omitted. A property written
+   * later stays: a redelivered batch cannot put an old address back.
+   */
+  at?: number | undefined;
+  events?: readonly BatchEvent[] | undefined;
+}
+export interface BatchEvent {
+  event: string;
+  payload?: Record<string, unknown> | undefined;
+  /** The occurrence's identity: a redelivered batch records it once. */
+  id?: string | undefined;
+  ts?: number | undefined;
+}
+export interface BatchResult {
+  profile?: IdentifyResult;
+  events: IngestResult[];
+}
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function isNonEmptyString(value: unknown): value is string;
+/** A profile value: a scalar or null (which removes the property). Nested values are not profile data. */
+export declare function isScalarOrNull(value: unknown): value is string | number | boolean | null;
+export declare const TS_ERROR = "ts must be a non-negative integer no later than 5 minutes in the future";
+/**
+ * A caller's timestamp: epoch milliseconds, whole, not negative, and not past the skew tolerance.
+ * A far-future ts would put the event ahead of everything a window condition reads, and a
+ * fractional or unsafe one does not survive the store.
+ */
+export declare function isValidTs(ts: unknown): ts is number;
+/** What is wrong with an untrusted identity: at least one id, and a user id outside the visitors' prefix. */
+export declare function identityError(userId: unknown, visitorId: unknown): string | undefined;
+export type ParsedBatch = {
+  ok: true;
+  batch: JourneyBatch;
+} | {
+  ok: false;
+  error: string;
+  issues?: readonly {
+    path: string;
+    message: string;
+  }[];
+};
+/**
+ * An untrusted batch, checked whole: one bad part refuses all of it, so a producer never has half
+ * a report applied. Contract `mode: 'report'` logs what it would refuse and keeps the original.
+ */
+export declare function parseBatch(raw: unknown, validation: IngestValidation): ParsedBatch;
+/**
+ * Apply a checked batch: the visitor's merge, the profile, then each event in order. Every part is idempotent (a
+ * property older than the stored one is skipped, an event id is stored once), so a caller retries
+ * a failed batch whole.
+ */
+export declare function ingestBatch(env: JourneyEnv, batch: JourneyBatch, store: JourneyStore): Promise<BatchResult>;
+/** A delivered queue message (the subset of the Cloudflare Queues `Message` used). */
+export interface QueueMessageLike {
+  id: string;
+  body: unknown;
+  /** Delivery attempts so far, this one included. */
+  attempts: number;
+  ack(): void;
+  retry(options?: {
+    delaySeconds?: number;
+  }): void;
+}
+/**
+ * Consume delivered batches one at a time. A batch that can never succeed is acknowledged, not
+ * retried: one the contract refuses (logged with the field paths, never the payload) and one for
+ * an erased user. Anything else is retried with a backoff until the queue's `max_retries` hands
+ * it to its dead letter queue.
+ */
+export declare function consumeBatches(env: JourneyEnv, messages: readonly QueueMessageLike[], store: JourneyStore, validation: IngestValidation): Promise<void>;
+//# sourceMappingURL=batch.d.mts.map

package/dist/host/batch.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.mts","names":[],"sources":["../../src/host/batch.ts"],"mappings":";;;;;;;;;;iBAuBiB;;EAEf;;EAEA;EACA,UAAU;;;;;EAKV;EACA,kBAAkB;;iBAGH;EACf;EACA,UAAU;;EAEV;EACA;;iBAGe;EACf,UAAU;EACV,QAAQ;;wBAGM,cAAc,iBAAiB,SAAS;wBAIxC,iBAAiB,iBAAiB;;wBAKlC,eAAe,iBAAiB;qBAWnC;;;;;;wBAOG,UAAU,cAAc;;wBAUxB,cAAc,iBAAiB;YAcnC;EACN;EAAU,OAAO;;EACjB;EAAW;EAAe;IAAoB;IAAc;;;;;;;wBAMlD,WAAW,cAAc,YAAY,mBAAmB;;;;;;wBAuElD,YACpB,KAAK,YACL,OAAO,cACP,OAAO,eACN,QAAQ;;iBAgBM;EACf;EACA;;EAEA;EACA;EACA,MAAM;IAAY;;;;;;;;;wBAcE,eACpB,KAAK,YACL,mBAAmB,oBACnB,OAAO,cACP,YAAY,mBACX"}