@shware/workflow 7.0.0 → 9.0.0

package/dist/store/index.d.cts

@@ -1,6 +1,7 @@
 import { BundleIR, ConditionIR, ScalarIR, WorkflowIR } from "../ir.cjs";
 import { PushDevice } from "../engine/ports.cjs";
 import { ErasureState, UserErasedError } from "./erasure.cjs";
+import { instanceOwner, isVisitorSubject, visitorIdOf, visitorSubject } from "./identity.cjs";
 import { JourneyFactSource } from "./facts.cjs";
 import { SqlClientLike } from "./sql.cjs";
 import { DEFAULT_SCHEMA, TABLES, TableSpec, UniqueConstraintSpec, renderDrizzleSchema, renderPostgresDdl } from "./tables.cjs";
@@ -36,6 +37,8 @@ export interface TriggerRoute {
   where: ConditionIR | null;
   /** Profile gate, or null. */
   filter: ConditionIR | null;
+  /** Whether a visitor not signed in may enter. */
+  visitors: boolean;
   /**
    * The code version that applied these routes; absent after a hand-posted `POST /deploy`. Read
    * in the same row as the hash, so the pair is always one deploy's.
@@ -136,11 +139,22 @@ export interface ExecutionRegistry {
 export type EntryOutcome = 'entered' | 'reclaimed' | null;
 /** A device registered for pushes: its provider token belongs to the user who registered it last. */
 export interface DeviceInput {
-  userId: string;
+  deviceId?: string | undefined;
+  /** Null until the device's visitor signs in. */
+  userId: string | null;
+  visitorId?: string | undefined;
   token: string;
   /** `ios` (APNs) or `android` (FCM): which provider the token belongs to. */
   platform: string;
-  ts: number;
+  at: number;
+}
+/** What linking a visitor to a user did; null when it was already linked, or to another user. */
+export interface VisitorMerge {
+  /** Instances dropped because the user is already in the same workflow: to stop. */
+  dropped: string[];
+  /** The event names and profile properties the user gained: their waits must wake. */
+  events: string[];
+  props: string[];
 }
 /** An instance of a user still in the ledger, and whether its runner was admitted (see `admitInstance`). */
 export interface RunningInstance {
@@ -327,6 +341,11 @@ export interface JourneyReporting {
     size: number;
   }[]>;
 }
+/** A user the segment sweep has to evaluate, and for which segments. */
+export interface SegmentCandidate {
+  userId: string;
+  segments: string[];
+}
 export interface JourneyStore {
   /** Where instances stand, every copy and its engagement, segment sizes. */
   readonly reporting: JourneyReporting;
@@ -419,34 +438,61 @@ export interface JourneyStore {
     payloads: Record<string, unknown>[];
     next?: EventCursor | undefined;
   }>;
+  /** The user a visitor became, if they did. */
+  linkedUser(visitorId: string): Promise<string | undefined>;
+  /** The visitor was heard from: who they are now, the user they became or their own subject. */
+  touchVisitor(visitorId: string, at: number): Promise<string>;
+  /**
+   * Forget visitors who never signed in and were last heard from before `before`, with no journey
+   * running: up to `limit` of them, leaving no tombstone. Answers how many.
+   */
+  pruneVisitors(before: number, limit: number): Promise<number>;
+  /**
+   * The visitor became the user: their events, profile, devices, opt-outs and journeys move to the
+   * user, once. A visitor already linked keeps its first user. The user's own entry wins over the
+   * visitor's in the same workflow, and the visitor's instance is dropped.
+   */
+  linkVisitor(visitorId: string, userId: string, at: number): Promise<VisitorMerge | null>;
+  /** Who an instance's entry belongs to now. */
+  entryOwner(instanceId: string): Promise<string | undefined>;
   getProfile(userId: string): Promise<ProfileProps | undefined>;
   /**
-   * Merge-patch `props` into the stored profile in one statement (a null
-   * removes the property) and return the result. One statement, because a
-   * read-modify-write loses one of two concurrent identifies.
+   * Merge-patch `props` into the stored profile (a null removes the property) and return the
+   * result, atomically: two concurrent identifies cannot lose each other's keys. `at` is when the
+   * values were read (now by default): a property written with a later `at` keeps its value, so
+   * a redelivered patch cannot undo a newer one.
    */
-  mergeProfile(userId: string, props: ProfileProps): Promise<ProfileProps>;
+  mergeProfile(userId: string, props: ProfileProps, at?: number): Promise<ProfileProps>;
   /**
-   * Every user the engine knows (a profile or an event): who the segment sweep evaluates. Ids
-   * come in ascending order; `after` resumes past the last id of the previous page, and `limit`
-   * bounds the page (the whole list without one).
+   * Who the segment sweep has to evaluate: for each user the engine knows (a profile, an event or
+   * a membership), the segments whose membership may have to change, or whose entry still owes a
+   * start. It may name a user whose membership turns out right, since `evaluateCondition` decides;
+   * it must not leave out one whose membership is wrong. Users come in ascending order; `after`
+   * resumes past the last id of the previous page, and users with nothing to do are left out.
    */
-  listUserIds(page?: {
+  listSegmentCandidates(page: {
+    segments: readonly {
+      id: string;
+      condition: ConditionIR;
+    }[];
+    now: number;
     after?: string | undefined;
-    limit?: number | undefined;
-  }): Promise<string[]>;
-  /** The user's push devices, most recently registered first. */
-  listDevices(userId: string): Promise<PushDevice[]>;
+    limit: number;
+  }): Promise<SegmentCandidate[]>;
+  /** The push devices a user or visitor holds now, most recently registered first. */
+  listDevices(subject: string): Promise<PushDevice[]>;
   /**
-   * Register a device: one row per token, so a token registered again moves to the user who
-   * registered it last (a phone signed into another account) and to the front of their list.
+   * Register a device: one row per token and per device, holding only its current owner. A token
+   * registered again moves to whoever registered it last (a phone signed into another account) and
+   * to the front of their list; a device's new token replaces its old one. Answers the previous
+   * owners, whose device waits must wake.
    */
-  upsertDevice(device: DeviceInput): Promise<void>;
-  /** Forget a token (reported dead by APNs / FCM); the user it belonged to, if any. */
+  upsertDevice(device: DeviceInput): Promise<string[]>;
+  /** Forget a token (reported dead by APNs / FCM); the user or visitor it belonged to, if any. */
   removeDevice(token: string): Promise<string | undefined>;
   /**
-   * The user signed out on the device: the token is kept, bound to nobody, until the next sign-in
-   * binds it again. The user it belonged to, if any.
+   * The user signed out on the device: the token is kept, bound to nobody, until the next
+   * registration binds it again. Who it belonged to, if anyone.
    */
   unbindDevice(token: string): Promise<string | undefined>;
   getSegmentCondition(id: string): Promise<ConditionIR | undefined>;
@@ -520,5 +566,5 @@ export interface JourneyStore {
   /** Drop every registration the handle holds. */
   unsubscribe(handle: string): Promise<void>;
 }
-export { DEFAULT_SCHEMA, type ErasureState, JourneyFactSource, PostgresJourneyStore, type PostgresJourneyStoreOptions, PostgresReporting, type SqlClientLike, TABLES, type TableSpec, type UniqueConstraintSpec, UserErasedError, renderDrizzleSchema, renderPostgresDdl };
+export { DEFAULT_SCHEMA, type ErasureState, JourneyFactSource, PostgresJourneyStore, type PostgresJourneyStoreOptions, PostgresReporting, type SqlClientLike, TABLES, type TableSpec, type UniqueConstraintSpec, UserErasedError, instanceOwner, isVisitorSubject, renderDrizzleSchema, renderPostgresDdl, visitorIdOf, visitorSubject };
 //# sourceMappingURL=index.d.cts.map

package/dist/store/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/store/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/store/index.ts"],"mappings":"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"}

package/dist/store/index.d.mts

@@ -1,6 +1,7 @@
 import { BundleIR, ConditionIR, ScalarIR, WorkflowIR } from "../ir.mjs";
 import { PushDevice } from "../engine/ports.mjs";
 import { ErasureState, UserErasedError } from "./erasure.mjs";
+import { instanceOwner, isVisitorSubject, visitorIdOf, visitorSubject } from "./identity.mjs";
 import { JourneyFactSource } from "./facts.mjs";
 import { SqlClientLike } from "./sql.mjs";
 import { DEFAULT_SCHEMA, TABLES, TableSpec, UniqueConstraintSpec, renderDrizzleSchema, renderPostgresDdl } from "./tables.mjs";
@@ -36,6 +37,8 @@ export interface TriggerRoute {
   where: ConditionIR | null;
   /** Profile gate, or null. */
   filter: ConditionIR | null;
+  /** Whether a visitor not signed in may enter. */
+  visitors: boolean;
   /**
    * The code version that applied these routes; absent after a hand-posted `POST /deploy`. Read
    * in the same row as the hash, so the pair is always one deploy's.
@@ -136,11 +139,22 @@ export interface ExecutionRegistry {
 export type EntryOutcome = 'entered' | 'reclaimed' | null;
 /** A device registered for pushes: its provider token belongs to the user who registered it last. */
 export interface DeviceInput {
-  userId: string;
+  deviceId?: string | undefined;
+  /** Null until the device's visitor signs in. */
+  userId: string | null;
+  visitorId?: string | undefined;
   token: string;
   /** `ios` (APNs) or `android` (FCM): which provider the token belongs to. */
   platform: string;
-  ts: number;
+  at: number;
+}
+/** What linking a visitor to a user did; null when it was already linked, or to another user. */
+export interface VisitorMerge {
+  /** Instances dropped because the user is already in the same workflow: to stop. */
+  dropped: string[];
+  /** The event names and profile properties the user gained: their waits must wake. */
+  events: string[];
+  props: string[];
 }
 /** An instance of a user still in the ledger, and whether its runner was admitted (see `admitInstance`). */
 export interface RunningInstance {
@@ -327,6 +341,11 @@ export interface JourneyReporting {
     size: number;
   }[]>;
 }
+/** A user the segment sweep has to evaluate, and for which segments. */
+export interface SegmentCandidate {
+  userId: string;
+  segments: string[];
+}
 export interface JourneyStore {
   /** Where instances stand, every copy and its engagement, segment sizes. */
   readonly reporting: JourneyReporting;
@@ -419,34 +438,61 @@ export interface JourneyStore {
     payloads: Record<string, unknown>[];
     next?: EventCursor | undefined;
   }>;
+  /** The user a visitor became, if they did. */
+  linkedUser(visitorId: string): Promise<string | undefined>;
+  /** The visitor was heard from: who they are now, the user they became or their own subject. */
+  touchVisitor(visitorId: string, at: number): Promise<string>;
+  /**
+   * Forget visitors who never signed in and were last heard from before `before`, with no journey
+   * running: up to `limit` of them, leaving no tombstone. Answers how many.
+   */
+  pruneVisitors(before: number, limit: number): Promise<number>;
+  /**
+   * The visitor became the user: their events, profile, devices, opt-outs and journeys move to the
+   * user, once. A visitor already linked keeps its first user. The user's own entry wins over the
+   * visitor's in the same workflow, and the visitor's instance is dropped.
+   */
+  linkVisitor(visitorId: string, userId: string, at: number): Promise<VisitorMerge | null>;
+  /** Who an instance's entry belongs to now. */
+  entryOwner(instanceId: string): Promise<string | undefined>;
   getProfile(userId: string): Promise<ProfileProps | undefined>;
   /**
-   * Merge-patch `props` into the stored profile in one statement (a null
-   * removes the property) and return the result. One statement, because a
-   * read-modify-write loses one of two concurrent identifies.
+   * Merge-patch `props` into the stored profile (a null removes the property) and return the
+   * result, atomically: two concurrent identifies cannot lose each other's keys. `at` is when the
+   * values were read (now by default): a property written with a later `at` keeps its value, so
+   * a redelivered patch cannot undo a newer one.
    */
-  mergeProfile(userId: string, props: ProfileProps): Promise<ProfileProps>;
+  mergeProfile(userId: string, props: ProfileProps, at?: number): Promise<ProfileProps>;
   /**
-   * Every user the engine knows (a profile or an event): who the segment sweep evaluates. Ids
-   * come in ascending order; `after` resumes past the last id of the previous page, and `limit`
-   * bounds the page (the whole list without one).
+   * Who the segment sweep has to evaluate: for each user the engine knows (a profile, an event or
+   * a membership), the segments whose membership may have to change, or whose entry still owes a
+   * start. It may name a user whose membership turns out right, since `evaluateCondition` decides;
+   * it must not leave out one whose membership is wrong. Users come in ascending order; `after`
+   * resumes past the last id of the previous page, and users with nothing to do are left out.
    */
-  listUserIds(page?: {
+  listSegmentCandidates(page: {
+    segments: readonly {
+      id: string;
+      condition: ConditionIR;
+    }[];
+    now: number;
     after?: string | undefined;
-    limit?: number | undefined;
-  }): Promise<string[]>;
-  /** The user's push devices, most recently registered first. */
-  listDevices(userId: string): Promise<PushDevice[]>;
+    limit: number;
+  }): Promise<SegmentCandidate[]>;
+  /** The push devices a user or visitor holds now, most recently registered first. */
+  listDevices(subject: string): Promise<PushDevice[]>;
   /**
-   * Register a device: one row per token, so a token registered again moves to the user who
-   * registered it last (a phone signed into another account) and to the front of their list.
+   * Register a device: one row per token and per device, holding only its current owner. A token
+   * registered again moves to whoever registered it last (a phone signed into another account) and
+   * to the front of their list; a device's new token replaces its old one. Answers the previous
+   * owners, whose device waits must wake.
    */
-  upsertDevice(device: DeviceInput): Promise<void>;
-  /** Forget a token (reported dead by APNs / FCM); the user it belonged to, if any. */
+  upsertDevice(device: DeviceInput): Promise<string[]>;
+  /** Forget a token (reported dead by APNs / FCM); the user or visitor it belonged to, if any. */
   removeDevice(token: string): Promise<string | undefined>;
   /**
-   * The user signed out on the device: the token is kept, bound to nobody, until the next sign-in
-   * binds it again. The user it belonged to, if any.
+   * The user signed out on the device: the token is kept, bound to nobody, until the next
+   * registration binds it again. Who it belonged to, if anyone.
    */
   unbindDevice(token: string): Promise<string | undefined>;
   getSegmentCondition(id: string): Promise<ConditionIR | undefined>;
@@ -520,5 +566,5 @@ export interface JourneyStore {
   /** Drop every registration the handle holds. */
   unsubscribe(handle: string): Promise<void>;
 }
-export { DEFAULT_SCHEMA, type ErasureState, JourneyFactSource, PostgresJourneyStore, type PostgresJourneyStoreOptions, PostgresReporting, type SqlClientLike, TABLES, type TableSpec, type UniqueConstraintSpec, UserErasedError, renderDrizzleSchema, renderPostgresDdl };
+export { DEFAULT_SCHEMA, type ErasureState, JourneyFactSource, PostgresJourneyStore, type PostgresJourneyStoreOptions, PostgresReporting, type SqlClientLike, TABLES, type TableSpec, type UniqueConstraintSpec, UserErasedError, instanceOwner, isVisitorSubject, renderDrizzleSchema, renderPostgresDdl, visitorIdOf, visitorSubject };
 //# sourceMappingURL=index.d.mts.map

package/dist/store/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/store/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/store/index.ts"],"mappings":"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"}

package/dist/store/index.mjs

@@ -1,5 +1,6 @@
 import { JourneyFactSource } from "./facts.mjs";
 import { UserErasedError } from "./erasure.mjs";
+import { instanceOwner, isVisitorSubject, visitorIdOf, visitorSubject } from "./identity.mjs";
 import { PostgresReporting } from "./postgres-reporting.mjs";
 import { DEFAULT_SCHEMA, TABLES, renderDrizzleSchema, renderPostgresDdl } from "./tables.mjs";
 import { PostgresJourneyStore } from "./postgres.mjs";
@@ -16,6 +17,6 @@ var SchemaMismatchError = class extends Error {
 		this.problems = problems;
 	}
 };
-export { DEFAULT_SCHEMA, JourneyFactSource, PostgresJourneyStore, PostgresReporting, SchemaMismatchError, TABLES, UserErasedError, renderDrizzleSchema, renderPostgresDdl };
+export { DEFAULT_SCHEMA, JourneyFactSource, PostgresJourneyStore, PostgresReporting, SchemaMismatchError, TABLES, UserErasedError, instanceOwner, isVisitorSubject, renderDrizzleSchema, renderPostgresDdl, visitorIdOf, visitorSubject };
 
 //# sourceMappingURL=index.mjs.map

package/dist/store/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/store/index.ts"],"sourcesContent":["import type { PushDevice } from '../engine/ports';\nimport type { BundleIR, ConditionIR, ScalarIR, WorkflowIR } from '../ir';\n\n/**\n * The journey engine's data plane. Postgres is the store (`PostgresJourneyStore`); this\n * interface is the port the host, the runner and the fact source use to persist or look\n * anything up, and what a test stub implements in its place. Execution (durable steps,\n * sleeps, wake-ups) is the workflow runtime's job and stays out of here.\n *\n * Timestamps are epoch milliseconds throughout; a store may persist them in\n * its native type as long as `sinceMs` comparisons behave.\n */\n\n/**\n * A profile patch or a stored profile. On the way in, `null` means \"remove\n * this property\" (RFC 7386 merge-patch, the only way the API has to unset\n * one); a stored profile never contains null.\n */\nexport type ProfileProps = Record<string, ScalarIR | null | undefined>;\n\nexport interface EventInput {\n  /** The occurrence's identity, chosen by the sender; a second insert with the same id is a no-op. */\n  id: string;\n  userId: string;\n  event: string;\n  ts: number;\n  payload: Record<string, unknown>;\n}\n\nexport interface TriggerRoute {\n  workflow: string;\n  hash: string;\n  /** Payload gate (payload-only condition tree), or null when the trigger has none. */\n  where: ConditionIR | null;\n  /** Profile gate, or null. */\n  filter: ConditionIR | null;\n  /**\n   * The code version that applied these routes; absent after a hand-posted `POST /deploy`. Read\n   * in the same row as the hash, so the pair is always one deploy's.\n   */\n  version?: string | undefined;\n}\n\nexport interface SegmentTriggerRoute {\n  workflow: string;\n  hash: string;\n  segment: string;\n  /** As `TriggerRoute.version`. */\n  version?: string | undefined;\n}\n\n/**\n * A Worker version, as Cloudflare's version metadata binding names it: the bundle compiled into\n * that version goes live only over an older one (`replaceRoutesIfNewer`).\n */\nexport interface BundleVersion {\n  id: string;\n  /** When the version was created (epoch ms): later versions are newer. */\n  createdAt: number;\n}\n\nexport interface EntryInput {\n  workflow: string;\n  userId: string;\n  instanceId: string;\n  hash: string;\n  ts: number;\n  /**\n   * The instance's start, recorded in the same transaction as the entry — for a runtime whose\n   * start is an asynchronous submit (AWS) that may have to be retried.\n   */\n  execution?: ExecutionStart | undefined;\n}\n\n/** How an instance is started on a runtime that submits it: replayed as is on every retry. */\nexport interface ExecutionStart {\n  /** The runtime's idempotency key (the durable execution name). */\n  name: string;\n  /** What is invoked: a qualified function ARN, its version included. */\n  target: string;\n  /** The exact payload: a retried submit must send the same bytes, or the runtime refuses it. */\n  input: string;\n}\n\nexport interface ExecutionRecord extends ExecutionStart {\n  instanceId: string;\n  workflow: string;\n  userId: string;\n  createdAt: number;\n  submittedAt?: number | undefined;\n  arn?: string | undefined;\n  unresolvedAt?: number | undefined;\n  callbackId?: string | undefined;\n  /** Bumped by every wait the instance arms: a wake or a cleanup of an older one leaves it alone. */\n  generation: number;\n  deadlineAt?: number | undefined;\n  checkedAt?: number | undefined;\n  stoppedAt?: number | undefined;\n}\n\n/**\n * What a runtime that submits its starts and parks waits on one-shot callbacks (AWS) keeps\n * beside the entry ledger. The runtime holds the execution history; this holds only the\n * mapping from the engine's instance id to it.\n */\nexport interface ExecutionRegistry {\n  get(instanceId: string): Promise<ExecutionRecord | undefined>;\n  /**\n   * Starts not yet confirmed and not given up on, oldest first: of one (workflow, user) entry\n   * still running, or every one created before `createdBefore`.\n   */\n  pendingStarts(filter: {\n    workflow?: string;\n    userId?: string;\n    createdBefore?: number;\n    limit: number;\n  }): Promise<ExecutionRecord[]>;\n  markSubmitted(instanceId: string, arn: string | undefined, at: number): Promise<void>;\n  markUnresolved(instanceId: string, at: number): Promise<void>;\n  setArn(instanceId: string, arn: string): Promise<void>;\n  /** Record the callback a wait parks on; false when a newer generation is already armed. */\n  armCallback(\n    instanceId: string,\n    callback: { id: string; generation: number; deadlineAt?: number | undefined }\n  ): Promise<boolean>;\n  /** Forget the callback — only if it is still that generation's. */\n  clearCallback(instanceId: string, generation: number): Promise<void>;\n  /** Submitted executions whose entry is still running, least recently checked first. */\n  toReconcile(limit: number, checkedBefore: number): Promise<ExecutionRecord[]>;\n  markChecked(instanceId: string, at: number): Promise<void>;\n  /** Record the first stop; a later one keeps it. */\n  markStopped(instanceId: string, at: number): Promise<void>;\n}\n\n/**\n * How an entry attempt ended: a fresh row, a 'failed' row of a dead instance\n * taken over (the once policy does not bar a user over one outage), or\n * refused because the pair already entered and is still alive.\n */\nexport type EntryOutcome = 'entered' | 'reclaimed' | null;\n\n/** A device registered for pushes: its provider token belongs to the user who registered it last. */\nexport interface DeviceInput {\n  userId: string;\n  token: string;\n  /** `ios` (APNs) or `android` (FCM): which provider the token belongs to. */\n  platform: string;\n  ts: number;\n}\n\n/** An instance of a user still in the ledger, and whether its runner was admitted (see `admitInstance`). */\nexport interface RunningInstance {\n  instanceId: string;\n  /** False until the runner admitted itself: nothing has run, and the tombstone keeps it that way. */\n  admitted: boolean;\n}\n\n/** One (workflow, user) entry: the attempt it records and how far that attempt got. */\nexport interface EntryState {\n  instanceId: string;\n  /** 'running' until the run finalizes it ('completed', 'goal', 'failed', …). */\n  status: string;\n  /** The runner admitted itself (`admitInstance`): the instance did reach the runtime. */\n  admitted: boolean;\n}\n\n/** An entry still waiting for its first admission (`unadmittedEntries`). */\nexport interface UnadmittedEntry {\n  instanceId: string;\n  workflow: string;\n  userId: string;\n}\n\n/** A store plus how to release what opening it acquired (a connection, say). */\nexport interface StoreLease {\n  store: JourneyStore;\n  close?: () => Promise<void>;\n}\n\nimport type { ErasureState } from './erasure';\n\nexport { type ErasureState, UserErasedError } from './erasure';\n\n/**\n * The live database lacks tables or columns the engine reads (an SDK upgrade added them, or the\n * host never ran the migration). Raised before a deploy writes anything.\n */\nexport class SchemaMismatchError extends Error {\n  override readonly name = 'SchemaMismatchError';\n\n  constructor(readonly problems: readonly string[]) {\n    super(\n      `the database does not match @shware/workflow's tables — regenerate the drizzle schema (workflow-ui generate) and run your migrations:\\n  ${problems.join('\\n  ')}`\n    );\n  }\n}\n\n/** A message copy as reporting records it, before it goes out. */\nexport interface MessageRecord {\n  idempotencyKey: string;\n  workflow: string;\n  instanceId: string;\n  nodeId: string;\n  template: string;\n  /** Where the copy lands: `email`, `push_ios`, `push_android`. */\n  channel: string;\n  userId: string;\n  /** An email's subscription topic; null for a transactional email and for every other channel. */\n  topic: string | null;\n  sentAt: number;\n}\n\n/** What is known of a copy without its engagement: whose it is, where it went, its topic. */\nexport interface MessageSummary {\n  userId: string;\n  channel: string;\n  topic: string | null;\n}\n\n/** One opt-out to set or clear: a topic of the channel, or the whole channel (`topic: null`). */\nexport interface SuppressionChange {\n  topic: string | null;\n  suppressed: boolean;\n}\n\n/** What a click is judged by. */\nexport interface ClickContext {\n  url: string;\n  deliveredAt: number;\n  linkCount: number;\n  /** The copy's clicks in the window before this one. */\n  recent: { position: number; at: number }[];\n}\n\n/** An open or a click, with the verdict on who made it and where it came from. */\nexport interface Engagement {\n  at: number;\n  machine: boolean;\n  /** The rule that called it a machine; null for a person. */\n  reason: string | null;\n  userAgent: string | null;\n  /** The network the request came from (Cloudflare's `cf.asn`, `cf.asOrganization`, `cf.country`), never the address. */\n  asn: number | null;\n  organization: string | null;\n  country: string | null;\n}\n\n/**\n * Journey reporting: where each instance stands, every copy and how it was engaged with, segment\n * sizes. The store exposes it as `reporting`; the host records it and serves email tracking.\n * Every write is idempotent — a retried step reports again.\n */\n/** Bounds on when an event happened, both inclusive (epoch ms); an absent side is open. */\nexport interface EventWindow {\n  sinceMs?: number;\n  untilMs?: number;\n}\n\n/**\n * Where a page of events ended: the last row's timestamp and id, the keyset `(ts, id)` the next\n * page starts after. Opaque to callers; `ts` is the store's own rendering of the timestamp, so a\n * round trip loses no precision.\n */\nexport interface EventCursor {\n  ts: string;\n  id: string;\n}\n\nexport interface JourneyReporting {\n  /** The instance entered: its row exists from here, so one a guard ends at once still counts. */\n  instanceStarted(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    at: number;\n  }): Promise<void>;\n  nodeReached(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    nodeId: string;\n    at: number;\n  }): Promise<void>;\n  instanceFinished(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    status: string;\n    at: number;\n    convertedAt?: number;\n  }): Promise<void>;\n  /** The copy's row id; the row a retry already wrote, when there is one. */\n  recordMessage(message: MessageRecord): Promise<string>;\n  /**\n   * Whether the copy was settled (`settleMessage`: delivered, or settled undelivered) — read from\n   * the database itself, so a replayed send step never trusts a cache that missed the settle.\n   */\n  messageSettled(idempotencyKey: string): Promise<boolean>;\n  settleMessage(\n    idempotencyKey: string,\n    result: { delivered: true } | { delivered: false; reason: string },\n    at: number\n  ): Promise<void>;\n  /** An email's tracked links, in document order. */\n  recordLinks(messageId: string, urls: readonly string[]): Promise<void>;\n  /**\n   * Record an open of the copy, judged by `judge` against the copy (its recipient and when it was\n   * delivered — when it was sent, before the transport answered); `undefined` from the judge\n   * records nothing. Read and written in one transaction. False for an unknown copy.\n   */\n  recordOpen(\n    messageId: string,\n    judge: (message: { userId: string; deliveredAt: number }) => Engagement | undefined\n  ): Promise<boolean>;\n  /**\n   * Record a click on the copy's link at `position`, judged by `judge` against the link, how\n   * many links the copy has and its clicks of the last `windowMs`. The copy is locked for the\n   * transaction, so clicks arriving together (a scanner following every link at once) are\n   * judged one after another, each seeing the ones before. When the judge asks to `backdate`,\n   * the window's earlier clicks are reclassified with this one's verdict. A click implies an\n   * open. Undefined for an unknown link.\n   */\n  recordClick(\n    messageId: string,\n    position: number,\n    at: number,\n    windowMs: number,\n    judge: (link: ClickContext) => { engagement: Engagement; backdate: boolean }\n  ): Promise<{ url: string; engagement: Engagement } | undefined>;\n  /**\n   * The email copy's recipient opted out: of the copy's topic, or with `scope: 'all'` of every\n   * email. Recorded on the copy and as a suppression (the topic's row, or the channel-wide\n   * null-topic row), in one transaction, which also yields who the recipient is and the topic —\n   * so the caller acts on the unsubscribe without a second read. A transactional copy\n   * (`topic: null`) has nothing to opt out of: nothing is recorded, and the answer says so.\n   * Undefined for an unknown copy.\n   */\n  recordUnsubscribe(\n    messageId: string,\n    at: number,\n    scope?: 'topic' | 'all'\n  ): Promise<{ userId: string; topic: string | null } | undefined>;\n  /** The copy's owner, channel and topic; undefined for an unknown copy. */\n  lookupMessage(messageId: string): Promise<MessageSummary | undefined>;\n  /** A push copy the device reported it received. False for an unknown copy. */\n  recordDeviceDelivered(messageId: string, at: number): Promise<boolean>;\n  /** Drop members of segments no longer deployed, then record every deployed segment's size. */\n  snapshotSegments(at: number): Promise<{ segment: string; size: number }[]>;\n}\n\nexport interface JourneyStore {\n  /** Where instances stand, every copy and its engagement, segment sizes. */\n  readonly reporting: JourneyReporting;\n\n  /**\n   * Record that the user's data must go (a deleted account): the tombstone every write about\n   * the user is conditional on, from here on and for good. Committed before anything is\n   * stopped or erased, so an entry that got in before it is found by the erasure and none gets\n   * in after it. Idempotent: a second request, or one for a user already erased, changes nothing.\n   */\n  requestErasure(userId: string, at: number): Promise<void>;\n  /** Users whose erasure was requested and not carried out yet (`'erasing'`), oldest first. */\n  pendingErasures(): Promise<string[]>;\n  /**\n   * Where the user stands: `'none'` (no tombstone), `'erasing'` (requested, their instances\n   * being stopped, data still there) or `'erased'` (`forgetUser` went through). Both\n   * tombstone states refuse every write about the user; the entry points read this for a fast\n   * answer, and the store's conditional writes are the gate itself.\n   */\n  erasureState(userId: string): Promise<ErasureState>;\n  /** The user's journey instances still running, by the entry ledger. */\n  runningInstances(userId: string): Promise<RunningInstance[]>;\n  /**\n   * The runner's admission, before its first observable effect: records that the instance runs\n   * (`admitted_at`, kept on replay) — unless the user has an erasure tombstone, in which case\n   * nothing is recorded and the runner must not run. Mutually exclusive with `requestErasure`\n   * and `forgetUser` for that user (Postgres: the user's advisory lock), so an erasure either\n   * finds the instance admitted and stops it, or commits its tombstone first and the admission\n   * is refused — never neither.\n   *\n   * A first admission needs the entry running. An instance already admitted is admitted again\n   * whatever the entry's status — the legitimate replay of an instance whose finalisation was\n   * cut short after the entry reached its terminal status, which resumes on its own checkpoint\n   * and finishes what is left. Never a new attempt's way in: false for a terminal entry never\n   * admitted, for an entry no longer in the ledger, for another user's entry, and for an\n   * instance whose entry was reclaimed since (`enterJourney` resets the admission with the\n   * instance id, so a superseded attempt cannot pass under the id it lost).\n   */\n  admitInstance(instanceId: string, userId: string): Promise<boolean>;\n  /**\n   * Erase everything kept about the user — profile, devices, events, wake subscriptions, segment\n   * memberships, entries and reporting — and mark the tombstone erased (`erased_at`), which\n   * stays: a write that was in flight when the data went cannot bring the user back, and the\n   * same id is never reactivated by ingest — which is also why the suppressions go with the\n   * rest: nothing is ever sent to the id again, so no opt-out needs keeping. Run only once no\n   * instance of theirs runs any more, or one could write some of it back. Idempotent. Mutually\n   * exclusive with every write about the user (the user's advisory lock), so the data is gone\n   * when this returns — nothing of theirs lands afterwards.\n   */\n  forgetUser(userId: string, at: number): Promise<void>;\n\n  /**\n   * The user opted out of the channel (recorded by an unsubscribe, or set through\n   * `/subscriptions`): with a `topic`, an opt-out of that topic or of the whole channel; without\n   * one, only the whole channel.\n   */\n  isSuppressed(userId: string, channel: string, topic?: string): Promise<boolean>;\n  /** Every opt-out of the user on the channel: the topics, and `null` for the whole channel. */\n  listSuppressions(userId: string, channel: string): Promise<(string | null)[]>;\n  /**\n   * Set or clear opt-outs, all in one transaction: a suppressed change inserts the row (keeping\n   * the time of one already there), an unsuppressed one deletes it. Written whatever the user's\n   * erasure state — the caller refuses an erased user first — since an opt-out is never refused.\n   */\n  updateSuppressions(\n    userId: string,\n    channel: string,\n    changes: readonly SuppressionChange[],\n    at: number\n  ): Promise<void>;\n\n  /**\n   * What the live database lacks against the engine's tables (read-only); a deploy refuses to\n   * run while it lists anything.\n   */\n  checkSchema(): Promise<string[]>;\n\n  /* ---------------------------------- events --------------------------------- */\n  /**\n   * Append the occurrence; false when its id was already in the log (nothing written). Throws\n   * `UserErasedError` for a user with a tombstone, like every write about a user below.\n   */\n  insertEvent(input: EventInput): Promise<boolean>;\n  /**\n   * Occurrences of `event` for the user, optionally only those within the window. With\n   * `atLeast`, counting may stop there: the result is exact below it and some number ≥ it\n   * otherwise — all a `performed(…, { count })` check needs, without counting a heavy user's\n   * whole history.\n   */\n  countEvents(\n    userId: string,\n    event: string,\n    window?: EventWindow,\n    atLeast?: number\n  ): Promise<number>;\n  /**\n   * One page of those occurrences' payloads, oldest first — the caller filters them with the\n   * shared evaluator and pages on with `next` only while it still needs matches, so a `where`\n   * never loads a user's whole history at once. `next` is absent on the last page.\n   */\n  pageEventPayloads(\n    userId: string,\n    event: string,\n    window: EventWindow | undefined,\n    page: { limit: number; after?: EventCursor | undefined }\n  ): Promise<{ payloads: Record<string, unknown>[]; next?: EventCursor | undefined }>;\n\n  /* --------------------------------- profiles -------------------------------- */\n  getProfile(userId: string): Promise<ProfileProps | undefined>;\n  /**\n   * Merge-patch `props` into the stored profile in one statement (a null\n   * removes the property) and return the result. One statement, because a\n   * read-modify-write loses one of two concurrent identifies.\n   */\n  mergeProfile(userId: string, props: ProfileProps): Promise<ProfileProps>;\n\n  /**\n   * Every user the engine knows (a profile or an event): who the segment sweep evaluates. Ids\n   * come in ascending order; `after` resumes past the last id of the previous page, and `limit`\n   * bounds the page (the whole list without one).\n   */\n  listUserIds(page?: { after?: string | undefined; limit?: number | undefined }): Promise<string[]>;\n\n  /* ---------------------------------- devices --------------------------------- */\n  /** The user's push devices, most recently registered first. */\n  listDevices(userId: string): Promise<PushDevice[]>;\n  /**\n   * Register a device: one row per token, so a token registered again moves to the user who\n   * registered it last (a phone signed into another account) and to the front of their list.\n   */\n  upsertDevice(device: DeviceInput): Promise<void>;\n  /** Forget a token (reported dead by APNs / FCM); the user it belonged to, if any. */\n  removeDevice(token: string): Promise<string | undefined>;\n  /**\n   * The user signed out on the device: the token is kept, bound to nobody, until the next sign-in\n   * binds it again. The user it belonged to, if any.\n   */\n  unbindDevice(token: string): Promise<string | undefined>;\n\n  /* ---------------------------- deployed definitions -------------------------- */\n  getSegmentCondition(id: string): Promise<ConditionIR | undefined>;\n  /** Every deployed segment with its definition: what the segment sweep evaluates. */\n  listSegments(): Promise<{ id: string; condition: ConditionIR }[]>;\n  findTriggers(event: string): Promise<TriggerRoute[]>;\n  listSegmentTriggers(): Promise<SegmentTriggerRoute[]>;\n  putWorkflowIR(workflow: WorkflowIR): Promise<void>;\n  getWorkflowIR(contentHash: string): Promise<WorkflowIR | undefined>;\n  /**\n   * Swap the routing tables (segments, event triggers, segment triggers) for\n   * the bundle's — atomically, so a concurrent ingest never sees them half\n   * empty. Workflow bodies are stored separately (`putWorkflowIR`) because they\n   * are content-addressed and outlive the routes that point at them.\n   *\n   * With `version` — a forced apply of the code's own bundle (`POST /bundle/deploy`) — the\n   * version is recorded too, unconditionally and in the same transaction, so the live version\n   * always names the code the routes came from. Without it (a hand-posted `POST /deploy`) the\n   * recorded version stays as it was: that bundle holds until a newer code version applies its own.\n   */\n  replaceRoutes(bundle: BundleIR, version?: BundleVersion): Promise<void>;\n  /**\n   * The Worker version whose bundle the routes came from, when one put them there (through\n   * `replaceRoutesIfNewer`, or a forced `replaceRoutes` with a version). Read from the database\n   * itself, not a cache in front of it.\n   */\n  liveBundleVersion(): Promise<BundleVersion | undefined>;\n  /**\n   * `replaceRoutes`, only when `version` is newer than the live one, recorded in the same\n   * transaction: two versions serving side by side during a rollout cannot leave the older one's\n   * routes in force. False, with nothing written, when a version as new or newer is live.\n   */\n  replaceRoutesIfNewer(bundle: BundleIR, version: BundleVersion): Promise<boolean>;\n\n  /* ----------------------------- segment membership --------------------------- */\n  isSegmentMember(segment: string, userId: string): Promise<boolean>;\n  /** Record the membership, with the workflows its entry has to start (see segment_start). */\n  addSegmentMember(\n    segment: string,\n    userId: string,\n    ts: number,\n    workflows: readonly string[]\n  ): Promise<void>;\n  /** The workflows the member's entry has not started yet. */\n  pendingSegmentStarts(segment: string, userId: string): Promise<string[]>;\n  completeSegmentStart(segment: string, userId: string, workflow: string): Promise<void>;\n  /** Drop the membership and any start it still owed. */\n  removeSegmentMember(segment: string, userId: string): Promise<void>;\n\n  /* ------------------------------- entry ledger ------------------------------- */\n  /**\n   * Record the entry (the once policy). Atomic under concurrent ingests: of\n   * two racing attempts exactly one is 'entered' (or 'reclaimed', when the\n   * pair's previous instance is recorded as 'failed') and the other null.\n   */\n  enterJourney(entry: EntryInput): Promise<EntryOutcome>;\n  removeEntry(instanceId: string): Promise<void>;\n  setEntryStatus(instanceId: string, status: string): Promise<void>;\n  /** The (workflow, user) entry as it stands, read from the database itself; undefined if none. */\n  getEntry(workflow: string, userId: string): Promise<EntryState | undefined>;\n  /**\n   * Running entries no runner has admitted, claimed before `claimedBefore` (epoch ms), oldest\n   * first: candidates for a start that was lost between the claim and the platform's create.\n   */\n  unadmittedEntries(claimedBefore: number, limit: number): Promise<UnadmittedEntry[]>;\n  /**\n   * Mark a lost start `failed`, so the pair's next trigger reclaims it. Only while the entry is\n   * still running and unadmitted under this instance id; false when it moved on meanwhile.\n   */\n  failUnadmittedEntry(instanceId: string): Promise<boolean>;\n  /** Execution starts and wake callbacks, for a runtime that submits its starts (AWS). */\n  readonly executions: ExecutionRegistry;\n\n  /* ------------------------------ wake subscriptions --------------------------- */\n  /** Distinct wake handles registered for (user, event). */\n  findWakeHandles(userId: string, event: string): Promise<string[]>;\n  /** Register the handle for each event; repeated registrations are idempotent. */\n  subscribe(handle: string, userId: string, events: readonly string[], ts: number): Promise<void>;\n  /** Drop every registration the handle holds. */\n  unsubscribe(handle: string): Promise<void>;\n}\n\nexport { JourneyFactSource } from './facts';\nexport { PostgresJourneyStore } from './postgres';\nexport { PostgresReporting } from './postgres-reporting';\nexport {\n  DEFAULT_SCHEMA,\n  TABLES,\n  renderDrizzleSchema,\n  renderPostgresDdl,\n  type TableSpec,\n  type UniqueConstraintSpec,\n} from './tables';\nexport type { PostgresJourneyStoreOptions, SqlClientLike } from './postgres';\n"],"mappings":";;;;;;;;;;AA2LA,IAAa,sBAAb,cAAyC,MAAM;CAGxB;CAFrB,OAAyB;CAEzB,YAAY,UAAsC;EAChD,MACE,4IAA4I,SAAS,KAAK,MAAM,GAClK;EAHmB,KAAA,WAAA;CAIrB;AACF"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/store/index.ts"],"sourcesContent":["import type { PushDevice } from '../engine/ports';\nimport type { BundleIR, ConditionIR, ScalarIR, WorkflowIR } from '../ir';\n\n/**\n * The journey engine's data plane. Postgres is the store (`PostgresJourneyStore`); this\n * interface is the port the host, the runner and the fact source use to persist or look\n * anything up, and what a test stub implements in its place. Execution (durable steps,\n * sleeps, wake-ups) is the workflow runtime's job and stays out of here.\n *\n * Timestamps are epoch milliseconds throughout; a store may persist them in\n * its native type as long as `sinceMs` comparisons behave.\n */\n\n/**\n * A profile patch or a stored profile. On the way in, `null` means \"remove\n * this property\" (RFC 7386 merge-patch, the only way the API has to unset\n * one); a stored profile never contains null.\n */\nexport type ProfileProps = Record<string, ScalarIR | null | undefined>;\n\nexport interface EventInput {\n  /** The occurrence's identity, chosen by the sender; a second insert with the same id is a no-op. */\n  id: string;\n  userId: string;\n  event: string;\n  ts: number;\n  payload: Record<string, unknown>;\n}\n\nexport interface TriggerRoute {\n  workflow: string;\n  hash: string;\n  /** Payload gate (payload-only condition tree), or null when the trigger has none. */\n  where: ConditionIR | null;\n  /** Profile gate, or null. */\n  filter: ConditionIR | null;\n  /** Whether a visitor not signed in may enter. */\n  visitors: boolean;\n  /**\n   * The code version that applied these routes; absent after a hand-posted `POST /deploy`. Read\n   * in the same row as the hash, so the pair is always one deploy's.\n   */\n  version?: string | undefined;\n}\n\nexport interface SegmentTriggerRoute {\n  workflow: string;\n  hash: string;\n  segment: string;\n  /** As `TriggerRoute.version`. */\n  version?: string | undefined;\n}\n\n/**\n * A Worker version, as Cloudflare's version metadata binding names it: the bundle compiled into\n * that version goes live only over an older one (`replaceRoutesIfNewer`).\n */\nexport interface BundleVersion {\n  id: string;\n  /** When the version was created (epoch ms): later versions are newer. */\n  createdAt: number;\n}\n\nexport interface EntryInput {\n  workflow: string;\n  userId: string;\n  instanceId: string;\n  hash: string;\n  ts: number;\n  /**\n   * The instance's start, recorded in the same transaction as the entry — for a runtime whose\n   * start is an asynchronous submit (AWS) that may have to be retried.\n   */\n  execution?: ExecutionStart | undefined;\n}\n\n/** How an instance is started on a runtime that submits it: replayed as is on every retry. */\nexport interface ExecutionStart {\n  /** The runtime's idempotency key (the durable execution name). */\n  name: string;\n  /** What is invoked: a qualified function ARN, its version included. */\n  target: string;\n  /** The exact payload: a retried submit must send the same bytes, or the runtime refuses it. */\n  input: string;\n}\n\nexport interface ExecutionRecord extends ExecutionStart {\n  instanceId: string;\n  workflow: string;\n  userId: string;\n  createdAt: number;\n  submittedAt?: number | undefined;\n  arn?: string | undefined;\n  unresolvedAt?: number | undefined;\n  callbackId?: string | undefined;\n  /** Bumped by every wait the instance arms: a wake or a cleanup of an older one leaves it alone. */\n  generation: number;\n  deadlineAt?: number | undefined;\n  checkedAt?: number | undefined;\n  stoppedAt?: number | undefined;\n}\n\n/**\n * What a runtime that submits its starts and parks waits on one-shot callbacks (AWS) keeps\n * beside the entry ledger. The runtime holds the execution history; this holds only the\n * mapping from the engine's instance id to it.\n */\nexport interface ExecutionRegistry {\n  get(instanceId: string): Promise<ExecutionRecord | undefined>;\n  /**\n   * Starts not yet confirmed and not given up on, oldest first: of one (workflow, user) entry\n   * still running, or every one created before `createdBefore`.\n   */\n  pendingStarts(filter: {\n    workflow?: string;\n    userId?: string;\n    createdBefore?: number;\n    limit: number;\n  }): Promise<ExecutionRecord[]>;\n  markSubmitted(instanceId: string, arn: string | undefined, at: number): Promise<void>;\n  markUnresolved(instanceId: string, at: number): Promise<void>;\n  setArn(instanceId: string, arn: string): Promise<void>;\n  /** Record the callback a wait parks on; false when a newer generation is already armed. */\n  armCallback(\n    instanceId: string,\n    callback: { id: string; generation: number; deadlineAt?: number | undefined }\n  ): Promise<boolean>;\n  /** Forget the callback — only if it is still that generation's. */\n  clearCallback(instanceId: string, generation: number): Promise<void>;\n  /** Submitted executions whose entry is still running, least recently checked first. */\n  toReconcile(limit: number, checkedBefore: number): Promise<ExecutionRecord[]>;\n  markChecked(instanceId: string, at: number): Promise<void>;\n  /** Record the first stop; a later one keeps it. */\n  markStopped(instanceId: string, at: number): Promise<void>;\n}\n\n/**\n * How an entry attempt ended: a fresh row, a 'failed' row of a dead instance\n * taken over (the once policy does not bar a user over one outage), or\n * refused because the pair already entered and is still alive.\n */\nexport type EntryOutcome = 'entered' | 'reclaimed' | null;\n\n/** A device registered for pushes: its provider token belongs to the user who registered it last. */\nexport interface DeviceInput {\n  deviceId?: string | undefined;\n  /** Null until the device's visitor signs in. */\n  userId: string | null;\n  visitorId?: string | undefined;\n  token: string;\n  /** `ios` (APNs) or `android` (FCM): which provider the token belongs to. */\n  platform: string;\n  at: number;\n}\n\n/** What linking a visitor to a user did; null when it was already linked, or to another user. */\nexport interface VisitorMerge {\n  /** Instances dropped because the user is already in the same workflow: to stop. */\n  dropped: string[];\n  /** The event names and profile properties the user gained: their waits must wake. */\n  events: string[];\n  props: string[];\n}\n\n/** An instance of a user still in the ledger, and whether its runner was admitted (see `admitInstance`). */\nexport interface RunningInstance {\n  instanceId: string;\n  /** False until the runner admitted itself: nothing has run, and the tombstone keeps it that way. */\n  admitted: boolean;\n}\n\n/** One (workflow, user) entry: the attempt it records and how far that attempt got. */\nexport interface EntryState {\n  instanceId: string;\n  /** 'running' until the run finalizes it ('completed', 'goal', 'failed', …). */\n  status: string;\n  /** The runner admitted itself (`admitInstance`): the instance did reach the runtime. */\n  admitted: boolean;\n}\n\n/** An entry still waiting for its first admission (`unadmittedEntries`). */\nexport interface UnadmittedEntry {\n  instanceId: string;\n  workflow: string;\n  userId: string;\n}\n\n/** A store plus how to release what opening it acquired (a connection, say). */\nexport interface StoreLease {\n  store: JourneyStore;\n  close?: () => Promise<void>;\n}\n\nimport type { ErasureState } from './erasure';\n\nexport { type ErasureState, UserErasedError } from './erasure';\nexport { instanceOwner, isVisitorSubject, visitorIdOf, visitorSubject } from './identity';\n\n/**\n * The live database lacks tables or columns the engine reads (an SDK upgrade added them, or the\n * host never ran the migration). Raised before a deploy writes anything.\n */\nexport class SchemaMismatchError extends Error {\n  override readonly name = 'SchemaMismatchError';\n\n  constructor(readonly problems: readonly string[]) {\n    super(\n      `the database does not match @shware/workflow's tables — regenerate the drizzle schema (workflow-ui generate) and run your migrations:\\n  ${problems.join('\\n  ')}`\n    );\n  }\n}\n\n/** A message copy as reporting records it, before it goes out. */\nexport interface MessageRecord {\n  idempotencyKey: string;\n  workflow: string;\n  instanceId: string;\n  nodeId: string;\n  template: string;\n  /** Where the copy lands: `email`, `push_ios`, `push_android`. */\n  channel: string;\n  userId: string;\n  /** An email's subscription topic; null for a transactional email and for every other channel. */\n  topic: string | null;\n  sentAt: number;\n}\n\n/** What is known of a copy without its engagement: whose it is, where it went, its topic. */\nexport interface MessageSummary {\n  userId: string;\n  channel: string;\n  topic: string | null;\n}\n\n/** One opt-out to set or clear: a topic of the channel, or the whole channel (`topic: null`). */\nexport interface SuppressionChange {\n  topic: string | null;\n  suppressed: boolean;\n}\n\n/** What a click is judged by. */\nexport interface ClickContext {\n  url: string;\n  deliveredAt: number;\n  linkCount: number;\n  /** The copy's clicks in the window before this one. */\n  recent: { position: number; at: number }[];\n}\n\n/** An open or a click, with the verdict on who made it and where it came from. */\nexport interface Engagement {\n  at: number;\n  machine: boolean;\n  /** The rule that called it a machine; null for a person. */\n  reason: string | null;\n  userAgent: string | null;\n  /** The network the request came from (Cloudflare's `cf.asn`, `cf.asOrganization`, `cf.country`), never the address. */\n  asn: number | null;\n  organization: string | null;\n  country: string | null;\n}\n\n/**\n * Journey reporting: where each instance stands, every copy and how it was engaged with, segment\n * sizes. The store exposes it as `reporting`; the host records it and serves email tracking.\n * Every write is idempotent — a retried step reports again.\n */\n/** Bounds on when an event happened, both inclusive (epoch ms); an absent side is open. */\nexport interface EventWindow {\n  sinceMs?: number;\n  untilMs?: number;\n}\n\n/**\n * Where a page of events ended: the last row's timestamp and id, the keyset `(ts, id)` the next\n * page starts after. Opaque to callers; `ts` is the store's own rendering of the timestamp, so a\n * round trip loses no precision.\n */\nexport interface EventCursor {\n  ts: string;\n  id: string;\n}\n\nexport interface JourneyReporting {\n  /** The instance entered: its row exists from here, so one a guard ends at once still counts. */\n  instanceStarted(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    at: number;\n  }): Promise<void>;\n  nodeReached(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    nodeId: string;\n    at: number;\n  }): Promise<void>;\n  instanceFinished(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    status: string;\n    at: number;\n    convertedAt?: number;\n  }): Promise<void>;\n  /** The copy's row id; the row a retry already wrote, when there is one. */\n  recordMessage(message: MessageRecord): Promise<string>;\n  /**\n   * Whether the copy was settled (`settleMessage`: delivered, or settled undelivered) — read from\n   * the database itself, so a replayed send step never trusts a cache that missed the settle.\n   */\n  messageSettled(idempotencyKey: string): Promise<boolean>;\n  settleMessage(\n    idempotencyKey: string,\n    result: { delivered: true } | { delivered: false; reason: string },\n    at: number\n  ): Promise<void>;\n  /** An email's tracked links, in document order. */\n  recordLinks(messageId: string, urls: readonly string[]): Promise<void>;\n  /**\n   * Record an open of the copy, judged by `judge` against the copy (its recipient and when it was\n   * delivered — when it was sent, before the transport answered); `undefined` from the judge\n   * records nothing. Read and written in one transaction. False for an unknown copy.\n   */\n  recordOpen(\n    messageId: string,\n    judge: (message: { userId: string; deliveredAt: number }) => Engagement | undefined\n  ): Promise<boolean>;\n  /**\n   * Record a click on the copy's link at `position`, judged by `judge` against the link, how\n   * many links the copy has and its clicks of the last `windowMs`. The copy is locked for the\n   * transaction, so clicks arriving together (a scanner following every link at once) are\n   * judged one after another, each seeing the ones before. When the judge asks to `backdate`,\n   * the window's earlier clicks are reclassified with this one's verdict. A click implies an\n   * open. Undefined for an unknown link.\n   */\n  recordClick(\n    messageId: string,\n    position: number,\n    at: number,\n    windowMs: number,\n    judge: (link: ClickContext) => { engagement: Engagement; backdate: boolean }\n  ): Promise<{ url: string; engagement: Engagement } | undefined>;\n  /**\n   * The email copy's recipient opted out: of the copy's topic, or with `scope: 'all'` of every\n   * email. Recorded on the copy and as a suppression (the topic's row, or the channel-wide\n   * null-topic row), in one transaction, which also yields who the recipient is and the topic —\n   * so the caller acts on the unsubscribe without a second read. A transactional copy\n   * (`topic: null`) has nothing to opt out of: nothing is recorded, and the answer says so.\n   * Undefined for an unknown copy.\n   */\n  recordUnsubscribe(\n    messageId: string,\n    at: number,\n    scope?: 'topic' | 'all'\n  ): Promise<{ userId: string; topic: string | null } | undefined>;\n  /** The copy's owner, channel and topic; undefined for an unknown copy. */\n  lookupMessage(messageId: string): Promise<MessageSummary | undefined>;\n  /** A push copy the device reported it received. False for an unknown copy. */\n  recordDeviceDelivered(messageId: string, at: number): Promise<boolean>;\n  /** Drop members of segments no longer deployed, then record every deployed segment's size. */\n  snapshotSegments(at: number): Promise<{ segment: string; size: number }[]>;\n}\n\n/** A user the segment sweep has to evaluate, and for which segments. */\nexport interface SegmentCandidate {\n  userId: string;\n  segments: string[];\n}\n\nexport interface JourneyStore {\n  /** Where instances stand, every copy and its engagement, segment sizes. */\n  readonly reporting: JourneyReporting;\n\n  /**\n   * Record that the user's data must go (a deleted account): the tombstone every write about\n   * the user is conditional on, from here on and for good. Committed before anything is\n   * stopped or erased, so an entry that got in before it is found by the erasure and none gets\n   * in after it. Idempotent: a second request, or one for a user already erased, changes nothing.\n   */\n  requestErasure(userId: string, at: number): Promise<void>;\n  /** Users whose erasure was requested and not carried out yet (`'erasing'`), oldest first. */\n  pendingErasures(): Promise<string[]>;\n  /**\n   * Where the user stands: `'none'` (no tombstone), `'erasing'` (requested, their instances\n   * being stopped, data still there) or `'erased'` (`forgetUser` went through). Both\n   * tombstone states refuse every write about the user; the entry points read this for a fast\n   * answer, and the store's conditional writes are the gate itself.\n   */\n  erasureState(userId: string): Promise<ErasureState>;\n  /** The user's journey instances still running, by the entry ledger. */\n  runningInstances(userId: string): Promise<RunningInstance[]>;\n  /**\n   * The runner's admission, before its first observable effect: records that the instance runs\n   * (`admitted_at`, kept on replay) — unless the user has an erasure tombstone, in which case\n   * nothing is recorded and the runner must not run. Mutually exclusive with `requestErasure`\n   * and `forgetUser` for that user (Postgres: the user's advisory lock), so an erasure either\n   * finds the instance admitted and stops it, or commits its tombstone first and the admission\n   * is refused — never neither.\n   *\n   * A first admission needs the entry running. An instance already admitted is admitted again\n   * whatever the entry's status — the legitimate replay of an instance whose finalisation was\n   * cut short after the entry reached its terminal status, which resumes on its own checkpoint\n   * and finishes what is left. Never a new attempt's way in: false for a terminal entry never\n   * admitted, for an entry no longer in the ledger, for another user's entry, and for an\n   * instance whose entry was reclaimed since (`enterJourney` resets the admission with the\n   * instance id, so a superseded attempt cannot pass under the id it lost).\n   */\n  admitInstance(instanceId: string, userId: string): Promise<boolean>;\n  /**\n   * Erase everything kept about the user — profile, devices, events, wake subscriptions, segment\n   * memberships, entries and reporting — and mark the tombstone erased (`erased_at`), which\n   * stays: a write that was in flight when the data went cannot bring the user back, and the\n   * same id is never reactivated by ingest — which is also why the suppressions go with the\n   * rest: nothing is ever sent to the id again, so no opt-out needs keeping. Run only once no\n   * instance of theirs runs any more, or one could write some of it back. Idempotent. Mutually\n   * exclusive with every write about the user (the user's advisory lock), so the data is gone\n   * when this returns — nothing of theirs lands afterwards.\n   */\n  forgetUser(userId: string, at: number): Promise<void>;\n\n  /**\n   * The user opted out of the channel (recorded by an unsubscribe, or set through\n   * `/subscriptions`): with a `topic`, an opt-out of that topic or of the whole channel; without\n   * one, only the whole channel.\n   */\n  isSuppressed(userId: string, channel: string, topic?: string): Promise<boolean>;\n  /** Every opt-out of the user on the channel: the topics, and `null` for the whole channel. */\n  listSuppressions(userId: string, channel: string): Promise<(string | null)[]>;\n  /**\n   * Set or clear opt-outs, all in one transaction: a suppressed change inserts the row (keeping\n   * the time of one already there), an unsuppressed one deletes it. Written whatever the user's\n   * erasure state — the caller refuses an erased user first — since an opt-out is never refused.\n   */\n  updateSuppressions(\n    userId: string,\n    channel: string,\n    changes: readonly SuppressionChange[],\n    at: number\n  ): Promise<void>;\n\n  /**\n   * What the live database lacks against the engine's tables (read-only); a deploy refuses to\n   * run while it lists anything.\n   */\n  checkSchema(): Promise<string[]>;\n\n  /* ---------------------------------- events --------------------------------- */\n  /**\n   * Append the occurrence; false when its id was already in the log (nothing written). Throws\n   * `UserErasedError` for a user with a tombstone, like every write about a user below.\n   */\n  insertEvent(input: EventInput): Promise<boolean>;\n  /**\n   * Occurrences of `event` for the user, optionally only those within the window. With\n   * `atLeast`, counting may stop there: the result is exact below it and some number ≥ it\n   * otherwise — all a `performed(…, { count })` check needs, without counting a heavy user's\n   * whole history.\n   */\n  countEvents(\n    userId: string,\n    event: string,\n    window?: EventWindow,\n    atLeast?: number\n  ): Promise<number>;\n  /**\n   * One page of those occurrences' payloads, oldest first — the caller filters them with the\n   * shared evaluator and pages on with `next` only while it still needs matches, so a `where`\n   * never loads a user's whole history at once. `next` is absent on the last page.\n   */\n  pageEventPayloads(\n    userId: string,\n    event: string,\n    window: EventWindow | undefined,\n    page: { limit: number; after?: EventCursor | undefined }\n  ): Promise<{ payloads: Record<string, unknown>[]; next?: EventCursor | undefined }>;\n\n  /* -------------------------------- visitors --------------------------------- */\n  /** The user a visitor became, if they did. */\n  linkedUser(visitorId: string): Promise<string | undefined>;\n  /** The visitor was heard from: who they are now, the user they became or their own subject. */\n  touchVisitor(visitorId: string, at: number): Promise<string>;\n  /**\n   * Forget visitors who never signed in and were last heard from before `before`, with no journey\n   * running: up to `limit` of them, leaving no tombstone. Answers how many.\n   */\n  pruneVisitors(before: number, limit: number): Promise<number>;\n  /**\n   * The visitor became the user: their events, profile, devices, opt-outs and journeys move to the\n   * user, once. A visitor already linked keeps its first user. The user's own entry wins over the\n   * visitor's in the same workflow, and the visitor's instance is dropped.\n   */\n  linkVisitor(visitorId: string, userId: string, at: number): Promise<VisitorMerge | null>;\n  /** Who an instance's entry belongs to now. */\n  entryOwner(instanceId: string): Promise<string | undefined>;\n\n  /* --------------------------------- profiles -------------------------------- */\n  getProfile(userId: string): Promise<ProfileProps | undefined>;\n  /**\n   * Merge-patch `props` into the stored profile (a null removes the property) and return the\n   * result, atomically: two concurrent identifies cannot lose each other's keys. `at` is when the\n   * values were read (now by default): a property written with a later `at` keeps its value, so\n   * a redelivered patch cannot undo a newer one.\n   */\n  mergeProfile(userId: string, props: ProfileProps, at?: number): Promise<ProfileProps>;\n\n  /**\n   * Who the segment sweep has to evaluate: for each user the engine knows (a profile, an event or\n   * a membership), the segments whose membership may have to change, or whose entry still owes a\n   * start. It may name a user whose membership turns out right, since `evaluateCondition` decides;\n   * it must not leave out one whose membership is wrong. Users come in ascending order; `after`\n   * resumes past the last id of the previous page, and users with nothing to do are left out.\n   */\n  listSegmentCandidates(page: {\n    segments: readonly { id: string; condition: ConditionIR }[];\n    now: number;\n    after?: string | undefined;\n    limit: number;\n  }): Promise<SegmentCandidate[]>;\n\n  /* ---------------------------------- devices --------------------------------- */\n  /** The push devices a user or visitor holds now, most recently registered first. */\n  listDevices(subject: string): Promise<PushDevice[]>;\n  /**\n   * Register a device: one row per token and per device, holding only its current owner. A token\n   * registered again moves to whoever registered it last (a phone signed into another account) and\n   * to the front of their list; a device's new token replaces its old one. Answers the previous\n   * owners, whose device waits must wake.\n   */\n  upsertDevice(device: DeviceInput): Promise<string[]>;\n  /** Forget a token (reported dead by APNs / FCM); the user or visitor it belonged to, if any. */\n  removeDevice(token: string): Promise<string | undefined>;\n  /**\n   * The user signed out on the device: the token is kept, bound to nobody, until the next\n   * registration binds it again. Who it belonged to, if anyone.\n   */\n  unbindDevice(token: string): Promise<string | undefined>;\n\n  /* ---------------------------- deployed definitions -------------------------- */\n  getSegmentCondition(id: string): Promise<ConditionIR | undefined>;\n  /** Every deployed segment with its definition: what the segment sweep evaluates. */\n  listSegments(): Promise<{ id: string; condition: ConditionIR }[]>;\n  findTriggers(event: string): Promise<TriggerRoute[]>;\n  listSegmentTriggers(): Promise<SegmentTriggerRoute[]>;\n  putWorkflowIR(workflow: WorkflowIR): Promise<void>;\n  getWorkflowIR(contentHash: string): Promise<WorkflowIR | undefined>;\n  /**\n   * Swap the routing tables (segments, event triggers, segment triggers) for\n   * the bundle's — atomically, so a concurrent ingest never sees them half\n   * empty. Workflow bodies are stored separately (`putWorkflowIR`) because they\n   * are content-addressed and outlive the routes that point at them.\n   *\n   * With `version` — a forced apply of the code's own bundle (`POST /bundle/deploy`) — the\n   * version is recorded too, unconditionally and in the same transaction, so the live version\n   * always names the code the routes came from. Without it (a hand-posted `POST /deploy`) the\n   * recorded version stays as it was: that bundle holds until a newer code version applies its own.\n   */\n  replaceRoutes(bundle: BundleIR, version?: BundleVersion): Promise<void>;\n  /**\n   * The Worker version whose bundle the routes came from, when one put them there (through\n   * `replaceRoutesIfNewer`, or a forced `replaceRoutes` with a version). Read from the database\n   * itself, not a cache in front of it.\n   */\n  liveBundleVersion(): Promise<BundleVersion | undefined>;\n  /**\n   * `replaceRoutes`, only when `version` is newer than the live one, recorded in the same\n   * transaction: two versions serving side by side during a rollout cannot leave the older one's\n   * routes in force. False, with nothing written, when a version as new or newer is live.\n   */\n  replaceRoutesIfNewer(bundle: BundleIR, version: BundleVersion): Promise<boolean>;\n\n  /* ----------------------------- segment membership --------------------------- */\n  isSegmentMember(segment: string, userId: string): Promise<boolean>;\n  /** Record the membership, with the workflows its entry has to start (see segment_start). */\n  addSegmentMember(\n    segment: string,\n    userId: string,\n    ts: number,\n    workflows: readonly string[]\n  ): Promise<void>;\n  /** The workflows the member's entry has not started yet. */\n  pendingSegmentStarts(segment: string, userId: string): Promise<string[]>;\n  completeSegmentStart(segment: string, userId: string, workflow: string): Promise<void>;\n  /** Drop the membership and any start it still owed. */\n  removeSegmentMember(segment: string, userId: string): Promise<void>;\n\n  /* ------------------------------- entry ledger ------------------------------- */\n  /**\n   * Record the entry (the once policy). Atomic under concurrent ingests: of\n   * two racing attempts exactly one is 'entered' (or 'reclaimed', when the\n   * pair's previous instance is recorded as 'failed') and the other null.\n   */\n  enterJourney(entry: EntryInput): Promise<EntryOutcome>;\n  removeEntry(instanceId: string): Promise<void>;\n  setEntryStatus(instanceId: string, status: string): Promise<void>;\n  /** The (workflow, user) entry as it stands, read from the database itself; undefined if none. */\n  getEntry(workflow: string, userId: string): Promise<EntryState | undefined>;\n  /**\n   * Running entries no runner has admitted, claimed before `claimedBefore` (epoch ms), oldest\n   * first: candidates for a start that was lost between the claim and the platform's create.\n   */\n  unadmittedEntries(claimedBefore: number, limit: number): Promise<UnadmittedEntry[]>;\n  /**\n   * Mark a lost start `failed`, so the pair's next trigger reclaims it. Only while the entry is\n   * still running and unadmitted under this instance id; false when it moved on meanwhile.\n   */\n  failUnadmittedEntry(instanceId: string): Promise<boolean>;\n  /** Execution starts and wake callbacks, for a runtime that submits its starts (AWS). */\n  readonly executions: ExecutionRegistry;\n\n  /* ------------------------------ wake subscriptions --------------------------- */\n  /** Distinct wake handles registered for (user, event). */\n  findWakeHandles(userId: string, event: string): Promise<string[]>;\n  /** Register the handle for each event; repeated registrations are idempotent. */\n  subscribe(handle: string, userId: string, events: readonly string[], ts: number): Promise<void>;\n  /** Drop every registration the handle holds. */\n  unsubscribe(handle: string): Promise<void>;\n}\n\nexport { JourneyFactSource } from './facts';\nexport { PostgresJourneyStore } from './postgres';\nexport { PostgresReporting } from './postgres-reporting';\nexport {\n  DEFAULT_SCHEMA,\n  TABLES,\n  renderDrizzleSchema,\n  renderPostgresDdl,\n  type TableSpec,\n  type UniqueConstraintSpec,\n} from './tables';\nexport type { PostgresJourneyStoreOptions, SqlClientLike } from './postgres';\n"],"mappings":";;;;;;;;;;;AA0MA,IAAa,sBAAb,cAAyC,MAAM;CAGxB;CAFrB,OAAyB;CAEzB,YAAY,UAAsC;EAChD,MACE,4IAA4I,SAAS,KAAK,MAAM,GAClK;EAHmB,KAAA,WAAA;CAIrB;AACF"}