@shware/workflow 3.3.0 → 4.1.0

package/dist/host/{router.d.cts → ingest.d.cts}

@@ -1,19 +1,7 @@
 import { TriggerIR } from "../ir.cjs";
-import { JourneyEnv } from "../cloudflare/bindings.cjs";
+import { JourneyEnv } from "./platform.cjs";
 import { BundleVersion, JourneyStore, ProfileProps } from "../store/index.cjs";
-import { Contract } from "../contract.cjs";
-//#region src/host/router.d.ts
-/**
- * Ingest router. An incoming event does four things: it is stored, it wakes
- * waiting instances, it is matched against event triggers, and it re-evaluates
- * segment-trigger membership. Plus /deploy (persist a bundle) and /identify
- * (merge a profile — which wakes property-condition waits via
- * PROFILE_UPDATED_EVENT and re-evaluates segment triggers too).
- *
- * Storage goes through a JourneyStore; the `store` argument defaults to the
- * D1 + KV store built from the env's bindings, so a Worker that only has those
- * calls these functions exactly as before.
- */
+//#region src/host/ingest.d.ts
 export interface IngestInput {
   userId: string;
   event: string;
@@ -44,6 +32,12 @@ export interface IngestResult {
   started: string[];
 }
 export declare function ingestEvent(env: JourneyEnv, input: IngestInput, store?: JourneyStore): Promise<IngestResult>;
+/**
+ * Wake every instance of the user waiting on any of `events`, once each: an instance subscribed
+ * to several of them (a wait on two profile properties, patched together) gets one wake-up, and
+ * the payload names the first event it matched.
+ */
+export declare function wakeSubscribers(env: JourneyEnv, store: JourneyStore, userId: string, events: readonly string[]): Promise<number>;
 /**
  * Segment-entry triggers, maintained lazily: on each ingest/identify for a
  * user, re-evaluate every trigger-routed segment for that user and act on the
@@ -63,12 +57,43 @@ export interface SweepResult {
     size: number;
   }[];
 }
+/** How many users one sweep page evaluates: a unit of resumable work (AWS checkpoints each). */
+export declare const SWEEP_PAGE_SIZE = 500;
+/**
+ * What the sweep does before it looks at any user: the runtime's own upkeep (AWS: unconfirmed
+ * starts, executions that ended unseen) and the erasures left unfinished (an instance would not
+ * stop). A failure of either is logged, never fatal: the pages still run. Users whose erasure is
+ * still pending afterwards are skipped by every page (`sweepSegmentsPaged`).
+ */
+export declare function sweepMaintenance(env: JourneyEnv, store: JourneyStore): Promise<void>;
+export interface SweepPage {
+  /** Users evaluated on this page (those being erased are listed but skipped). */
+  users: number;
+  /** Journeys the segments' entries started on this page. */
+  started: string[];
+  /** The last user id listed, to resume past (`after`); undefined when the page was empty. */
+  lastUserId?: string | undefined;
+  /** Whether the page was full, so another may follow. */
+  more: boolean;
+}
+/**
+ * One page of the sweep: the users after `after` (ascending, at most `limit`), every deployed
+ * segment evaluated for each. The pages are what makes the sweep resumable — a host whose run
+ * can be cut short (a Lambda timeout) checkpoints each one and replays the checkpointed pages
+ * instead of starting over; `sweepSegments` is the plain loop over them.
+ */
+export declare function sweepSegmentsPaged(env: JourneyEnv, store: JourneyStore, page: {
+  after?: string | undefined;
+  limit?: number | undefined;
+  now?: number | undefined;
+}): Promise<SweepPage>;
 /**
  * The scheduled sweep: every deployed segment evaluated for every known user — the evaluator a
  * journey's conditions run on, so a member is exactly who a journey would see in it. Membership
  * follows (joiners keep the time they joined, leavers are removed), segment triggers start the
  * journeys of whoever entered by the clock alone, and the store records each segment's size.
- * It walks users one by one: fine for thousands, a large audience wants SQL-side evaluation.
+ * It walks users page by page (`sweepSegmentsPaged`): fine for thousands, a large audience wants
+ * SQL-side evaluation.
  */
 export declare function sweepSegments(env: JourneyEnv, store: JourneyStore, now?: number): Promise<SweepResult>;
 export interface IdentifyResult {
@@ -99,9 +124,13 @@ export declare function registerDevice(env: JourneyEnv, device: DeviceRegistrati
   woke: number;
 }>;
 /**
- * Forget a user (a deleted account): the request is recorded first, then carried out. An
- * instance that will not stop leaves it pending — nothing erased yet — and the scheduled sweep
- * retries it; `erased: false` says so.
+ * Forget a user (a deleted account): the tombstone is committed first, then the erasure carried
+ * out. `erased: true` means every admitted runner of theirs was confirmed stopped, the entries
+ * never admitted can never run, and the data is deleted — for good, with no time window and no
+ * second pass: the tombstone commits under the user's lock, which every write about the user
+ * also takes, so nothing of theirs can land after it. An admitted instance that will not stop
+ * leaves it pending — nothing erased yet — and the scheduled sweep retries it; `erased: false`
+ * says so. A user already erased answers `erased: true` again, with nothing to do.
  */
 export declare function forgetUser(env: JourneyEnv, userId: string, store?: JourneyStore, now?: number): Promise<{
   ok: true;
@@ -157,16 +186,5 @@ export declare class BundleIntegrityError extends Error {
  * compiled into it; without one it is forced, whatever is live.
  */
 export declare function deployBundle(env: JourneyEnv, bundle: unknown, store?: JourneyStore, version?: BundleVersion): Promise<DeployResult>;
-/**
- * How the ingest API applies a contract: 'enforce' refuses an invalid event or
- * patch with a 400 before anything is stored, woken or started; 'report' logs
- * the issues (event id, name, field paths — never the payload) and accepts it,
- * for checking real producers before turning enforcement on.
- */
-export interface IngestValidation {
-  contract?: Contract | undefined;
-  mode?: 'enforce' | 'report' | undefined;
-}
-export declare function handleRequest(request: Request, env: JourneyEnv, store?: JourneyStore, validation?: IngestValidation): Promise<Response>;
 //#endregion
-//# sourceMappingURL=router.d.cts.map
+//# sourceMappingURL=ingest.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.cts","names":[],"sources":["../../src/host/ingest.ts"],"mappings":";;;;iBA+CiB;EACf;EACA;EACA,UAAU;EACV;;;;;;;;;;;;;;;EAeA;;iBAGe;;EAEf;;EAEA;EACA;EACA;;wBAGoB,YACpB,KAAK,YACL,OAAO,aACP,QAAO,eACN,QAAQ;;;;;;wBAwCW,gBACpB,KAAK,YACL,OAAO,cACP,gBACA,4BACC;;;;;;;;;wBA0EmB,uBACpB,KAAK,YACL,OAAO,cACP,gBACA,aACC;iBA0Fc;EACf;;EAEA;;EAEA;IAAS;IAAiB;;;;qBAIf;;;;;;;wBAQS,iBAAiB,KAAK,YAAY,OAAO,eAAe;iBAkB7D;;EAEf;;EAEA;;EAEA;;EAEA;;;;;;;;wBASoB,mBACpB,KAAK,YACL,OAAO,cACP;EAAQ;EAA4B;EAA4B;IAC/D,QAAQ;;;;;;;;;wBAsCW,cACpB,KAAK,YACL,OAAO,cACP,eACC,QAAQ;iBAgFM;EACf;EACA,OAAO;EACP;EACA;;;;;;;wBAQoB,aACpB,KAAK,YACL,gBACA,OAAO,cACP,QAAO,eACN,QAAQ;iBAiBM;EACf;EACA;EACA;EACA;;;;;;;wBAQoB,eACpB,KAAK,YACL,QAAQ,oBACR,QAAO,eACN;EAAU;EAAU;;;;;;;;;;;wBA2FD,WACpB,KAAK,YACL,gBACA,QAAO,cACP,eACC;EAAU;EAAU;EAAiB;;;;;;;wBAUlB,aACpB,KAAK,YACL,eACA,QAAO,eACN;EAAU;EAAU;;;wBAQD,aACpB,KAAK,YACL,eACA,QAAO,eACN;EAAU;EAAU;;iBASN;EACf;;;;;;;;EAQA;IAAY;IAAkB,SAAS;;;;;;EAKvC;;;qBAIW,8BAA8B;WACvB;EAClB;;;qBAMW,6BAA6B;EACxC,YAAY;;;;;;;;wBA8CQ,aACpB,KAAK,YACL,iBACA,QAAO,cACP,UAAU,gBACT,QAAQ"}

package/dist/host/{router.d.mts → ingest.d.mts}

@@ -1,19 +1,7 @@
 import { TriggerIR } from "../ir.mjs";
-import { JourneyEnv } from "../cloudflare/bindings.mjs";
+import { JourneyEnv } from "./platform.mjs";
 import { BundleVersion, JourneyStore, ProfileProps } from "../store/index.mjs";
-import { Contract } from "../contract.mjs";
-//#region src/host/router.d.ts
-/**
- * Ingest router. An incoming event does four things: it is stored, it wakes
- * waiting instances, it is matched against event triggers, and it re-evaluates
- * segment-trigger membership. Plus /deploy (persist a bundle) and /identify
- * (merge a profile — which wakes property-condition waits via
- * PROFILE_UPDATED_EVENT and re-evaluates segment triggers too).
- *
- * Storage goes through a JourneyStore; the `store` argument defaults to the
- * D1 + KV store built from the env's bindings, so a Worker that only has those
- * calls these functions exactly as before.
- */
+//#region src/host/ingest.d.ts
 export interface IngestInput {
   userId: string;
   event: string;
@@ -44,6 +32,12 @@ export interface IngestResult {
   started: string[];
 }
 export declare function ingestEvent(env: JourneyEnv, input: IngestInput, store?: JourneyStore): Promise<IngestResult>;
+/**
+ * Wake every instance of the user waiting on any of `events`, once each: an instance subscribed
+ * to several of them (a wait on two profile properties, patched together) gets one wake-up, and
+ * the payload names the first event it matched.
+ */
+export declare function wakeSubscribers(env: JourneyEnv, store: JourneyStore, userId: string, events: readonly string[]): Promise<number>;
 /**
  * Segment-entry triggers, maintained lazily: on each ingest/identify for a
  * user, re-evaluate every trigger-routed segment for that user and act on the
@@ -63,12 +57,43 @@ export interface SweepResult {
     size: number;
   }[];
 }
+/** How many users one sweep page evaluates: a unit of resumable work (AWS checkpoints each). */
+export declare const SWEEP_PAGE_SIZE = 500;
+/**
+ * What the sweep does before it looks at any user: the runtime's own upkeep (AWS: unconfirmed
+ * starts, executions that ended unseen) and the erasures left unfinished (an instance would not
+ * stop). A failure of either is logged, never fatal: the pages still run. Users whose erasure is
+ * still pending afterwards are skipped by every page (`sweepSegmentsPaged`).
+ */
+export declare function sweepMaintenance(env: JourneyEnv, store: JourneyStore): Promise<void>;
+export interface SweepPage {
+  /** Users evaluated on this page (those being erased are listed but skipped). */
+  users: number;
+  /** Journeys the segments' entries started on this page. */
+  started: string[];
+  /** The last user id listed, to resume past (`after`); undefined when the page was empty. */
+  lastUserId?: string | undefined;
+  /** Whether the page was full, so another may follow. */
+  more: boolean;
+}
+/**
+ * One page of the sweep: the users after `after` (ascending, at most `limit`), every deployed
+ * segment evaluated for each. The pages are what makes the sweep resumable — a host whose run
+ * can be cut short (a Lambda timeout) checkpoints each one and replays the checkpointed pages
+ * instead of starting over; `sweepSegments` is the plain loop over them.
+ */
+export declare function sweepSegmentsPaged(env: JourneyEnv, store: JourneyStore, page: {
+  after?: string | undefined;
+  limit?: number | undefined;
+  now?: number | undefined;
+}): Promise<SweepPage>;
 /**
  * The scheduled sweep: every deployed segment evaluated for every known user — the evaluator a
  * journey's conditions run on, so a member is exactly who a journey would see in it. Membership
  * follows (joiners keep the time they joined, leavers are removed), segment triggers start the
  * journeys of whoever entered by the clock alone, and the store records each segment's size.
- * It walks users one by one: fine for thousands, a large audience wants SQL-side evaluation.
+ * It walks users page by page (`sweepSegmentsPaged`): fine for thousands, a large audience wants
+ * SQL-side evaluation.
  */
 export declare function sweepSegments(env: JourneyEnv, store: JourneyStore, now?: number): Promise<SweepResult>;
 export interface IdentifyResult {
@@ -99,9 +124,13 @@ export declare function registerDevice(env: JourneyEnv, device: DeviceRegistrati
   woke: number;
 }>;
 /**
- * Forget a user (a deleted account): the request is recorded first, then carried out. An
- * instance that will not stop leaves it pending — nothing erased yet — and the scheduled sweep
- * retries it; `erased: false` says so.
+ * Forget a user (a deleted account): the tombstone is committed first, then the erasure carried
+ * out. `erased: true` means every admitted runner of theirs was confirmed stopped, the entries
+ * never admitted can never run, and the data is deleted — for good, with no time window and no
+ * second pass: the tombstone commits under the user's lock, which every write about the user
+ * also takes, so nothing of theirs can land after it. An admitted instance that will not stop
+ * leaves it pending — nothing erased yet — and the scheduled sweep retries it; `erased: false`
+ * says so. A user already erased answers `erased: true` again, with nothing to do.
  */
 export declare function forgetUser(env: JourneyEnv, userId: string, store?: JourneyStore, now?: number): Promise<{
   ok: true;
@@ -157,16 +186,5 @@ export declare class BundleIntegrityError extends Error {
  * compiled into it; without one it is forced, whatever is live.
  */
 export declare function deployBundle(env: JourneyEnv, bundle: unknown, store?: JourneyStore, version?: BundleVersion): Promise<DeployResult>;
-/**
- * How the ingest API applies a contract: 'enforce' refuses an invalid event or
- * patch with a 400 before anything is stored, woken or started; 'report' logs
- * the issues (event id, name, field paths — never the payload) and accepts it,
- * for checking real producers before turning enforcement on.
- */
-export interface IngestValidation {
-  contract?: Contract | undefined;
-  mode?: 'enforce' | 'report' | undefined;
-}
-export declare function handleRequest(request: Request, env: JourneyEnv, store?: JourneyStore, validation?: IngestValidation): Promise<Response>;
 //#endregion
-//# sourceMappingURL=router.d.mts.map
+//# sourceMappingURL=ingest.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.mts","names":[],"sources":["../../src/host/ingest.ts"],"mappings":";;;;iBA+CiB;EACf;EACA;EACA,UAAU;EACV;;;;;;;;;;;;;;;EAeA;;iBAGe;;EAEf;;EAEA;EACA;EACA;;wBAGoB,YACpB,KAAK,YACL,OAAO,aACP,QAAO,eACN,QAAQ;;;;;;wBAwCW,gBACpB,KAAK,YACL,OAAO,cACP,gBACA,4BACC;;;;;;;;;wBA0EmB,uBACpB,KAAK,YACL,OAAO,cACP,gBACA,aACC;iBA0Fc;EACf;;EAEA;;EAEA;IAAS;IAAiB;;;;qBAIf;;;;;;;wBAQS,iBAAiB,KAAK,YAAY,OAAO,eAAe;iBAkB7D;;EAEf;;EAEA;;EAEA;;EAEA;;;;;;;;wBASoB,mBACpB,KAAK,YACL,OAAO,cACP;EAAQ;EAA4B;EAA4B;IAC/D,QAAQ;;;;;;;;;wBAsCW,cACpB,KAAK,YACL,OAAO,cACP,eACC,QAAQ;iBAgFM;EACf;EACA,OAAO;EACP;EACA;;;;;;;wBAQoB,aACpB,KAAK,YACL,gBACA,OAAO,cACP,QAAO,eACN,QAAQ;iBAiBM;EACf;EACA;EACA;EACA;;;;;;;wBAQoB,eACpB,KAAK,YACL,QAAQ,oBACR,QAAO,eACN;EAAU;EAAU;;;;;;;;;;;wBA2FD,WACpB,KAAK,YACL,gBACA,QAAO,cACP,eACC;EAAU;EAAU;EAAiB;;;;;;;wBAUlB,aACpB,KAAK,YACL,eACA,QAAO,eACN;EAAU;EAAU;;;wBAQD,aACpB,KAAK,YACL,eACA,QAAO,eACN;EAAU;EAAU;;iBASN;EACf;;;;;;;;EAQA;IAAY;IAAkB,SAAS;;;;;;EAKvC;;;qBAIW,8BAA8B;WACvB;EAClB;;;qBAMW,6BAA6B;EACxC,YAAY;;;;;;;;wBA8CQ,aACpB,KAAK,YACL,iBACA,QAAO,cACP,UAAU,gBACT,QAAQ"}