@smthrs/triggers 0.0.0-stage → 1.0.0-rc.3

package/dist/cjs/ClaimDecision.d.ts

@@ -0,0 +1,183 @@
+/**
+ * The one claim decision both trigger stores apply.
+ *
+ * A claim is a pure function of the rows it reads: the trigger declaration,
+ * the fire row at the occurrence being claimed, and the fire row the active
+ * reservation holds. Each store gathers that snapshot in its own storage,
+ * calls {@link decide}, and applies the writes it answers. Writing the fences,
+ * the expired-reservation reclaim, and the supersede predecessor substitution
+ * once is what keeps `SqlTriggerStore` and the published in-memory store from
+ * drifting apart.
+ *
+ * @since 1.0.0-rc.0
+ */
+import type { Overlap as Policy } from "./Trigger.ts";
+import { TriggerError } from "./TriggerError.ts";
+import { type Claim, type ClaimFire, type Outcome } from "./TriggerStore.ts";
+/**
+ * A fire row as the decision reads it. `outcome` is `null` for a claimed but
+ * unsettled occurrence, matching the nullable column.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Fire {
+    readonly outcome: Outcome | null;
+    readonly runId?: string | undefined;
+}
+/**
+ * Everything the decision reads, gathered by the store before it runs.
+ *
+ * `existingFire` is absent when this claim is what created the row.
+ * `activeFire` is the row at `reservationOccurrence(activeRunId)`, read after
+ * that insert, and is needed only while `activeRunId` is a reservation.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Snapshot {
+    readonly revision: number;
+    readonly enabled: boolean;
+    readonly overlap: Policy;
+    readonly activeRunId?: string | undefined;
+    readonly activeClaimedAt?: number | undefined;
+    readonly pending?: number | undefined;
+    readonly existingFire?: Fire | undefined;
+    readonly activeFire?: Fire | undefined;
+}
+/**
+ * One durable edit a claim owes, in the order the store must apply them.
+ *
+ * `SetOutcome` with `whileOpen` may only settle a fire that is still `null` or
+ * `buffered`; the SQL store spells that as a `WHERE` clause.
+ * `ReleaseReservation` may only land while `expected` still owns the trigger.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Write = {
+    readonly _tag: "SetOutcome";
+    readonly occurrence: number;
+    readonly outcome: Outcome;
+    readonly whileOpen: boolean;
+} | {
+    readonly _tag: "SetRunId";
+    readonly occurrence: number;
+    readonly runId: string;
+} | {
+    readonly _tag: "ReleaseReservation";
+    readonly expected: string;
+    readonly activeRunId?: string | undefined;
+    readonly pending?: number | undefined;
+} | {
+    readonly _tag: "AdvanceCursor";
+    readonly occurrence: number;
+} | {
+    readonly _tag: "SetPending";
+    readonly occurrence: number;
+} | {
+    readonly _tag: "Reserve";
+    readonly reservationId: string;
+    readonly claimedAt: number;
+};
+/**
+ * What a claim decided: a refusal the store fails with, or a claim outcome and
+ * the writes that make it durable. An unclaimed occurrence answers
+ * `{ claimed: false }` with no writes.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Decision = {
+    readonly _tag: "Refused";
+    readonly error: TriggerError;
+} | {
+    readonly _tag: "Decided";
+    readonly claim: Claim;
+    readonly writes: ReadonlyArray<Write>;
+};
+/**
+ * The claim request, the rows it reads, the reservation id the store minted
+ * for it, and the store clock reading it was claimed at.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Input {
+    readonly fire: ClaimFire;
+    readonly snapshot: Snapshot;
+    readonly reservationId: string;
+    readonly claimedAt: number;
+}
+type AdmittedDecision = Extract<Decision, {
+    readonly _tag: "Decided";
+}>;
+/**
+ * What a reader finds behind a trigger's active owner: nothing, a live owner,
+ * or an expired reservation to release.
+ *
+ * `expected` is the reservation the release must still find in place.
+ * `recovered` is the launched predecessor the release hands back, and
+ * `pending` is the occurrence it re-arms; both are absent when the reservation
+ * covered no unsettled fire.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Lease = {
+    readonly _tag: "Idle";
+} | {
+    readonly _tag: "Held";
+    readonly runId: string;
+} | {
+    readonly _tag: "Expired";
+    readonly expected: string;
+    readonly recovered?: string | undefined;
+    readonly pending?: number | undefined;
+};
+/**
+ * Applies the reservation lease to a trigger's active owner.
+ *
+ * `unfinished` is the fire row at `reservationOccurrence(activeRunId)` while
+ * that row is still `null` or `buffered`, and is absent otherwise. A process
+ * that died after claiming an occurrence but before launching it left the
+ * reservation; the expired lease releases it and re-arms both ordinary and
+ * buffered work.
+ *
+ * @category decision
+ * @since 1.0.0-rc.0
+ */
+export declare const lease: (input: {
+    readonly activeRunId?: string | undefined;
+    readonly activeClaimedAt?: number | undefined;
+    readonly pending?: number | undefined;
+    readonly now: number;
+    readonly unfinished?: Fire | undefined;
+}) => Lease;
+/**
+ * The refusals a claim owes before it reads any fire row, in the order the
+ * stores apply them. A store checks these first so a refused claim leaves the
+ * ledger untouched; {@link decide} re-applies them so a store that only calls
+ * it is still fenced.
+ *
+ * @category decision
+ * @since 1.0.0-rc.0
+ */
+export declare const refuse: (snapshot: Pick<Snapshot, "enabled" | "revision">, fire: ClaimFire) => TriggerError | undefined;
+/**
+ * Applies the claim protocol to a snapshot.
+ *
+ * @category decision
+ * @since 1.0.0-rc.0
+ */
+export declare const decide: (input: Input) => Decision;
+/**
+ * Decides over a snapshot already admitted by {@link refuse} in the same
+ * transaction. This avoids checking the same immutable revision twice.
+ * @category decision
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export declare const decideFenced: ({ claimedAt, fire, reservationId, snapshot }: Input) => AdmittedDecision;
+export {};
+//# sourceMappingURL=ClaimDecision.d.ts.map

package/dist/cjs/ClaimDecision.d.ts.map

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

package/dist/cjs/ClaimDecision.js

@@ -0,0 +1,144 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ClaimDecision_exports = {};
+__export(ClaimDecision_exports, {
+  decide: () => decide,
+  decideFenced: () => decideFenced,
+  lease: () => lease,
+  refuse: () => refuse
+});
+module.exports = __toCommonJS(ClaimDecision_exports);
+var Overlap = __toESM(require("./Overlap.js"), 1);
+var import_TriggerError = require("./TriggerError.js");
+var import_TriggerStore = require("./TriggerStore.js");
+const decided = (claim, writes) => ({ _tag: "Decided", claim, writes });
+const lease = (input) => {
+  const { activeClaimedAt, activeRunId, now, pending, unfinished } = input;
+  if (activeRunId === void 0) return { _tag: "Idle" };
+  if (!(0, import_TriggerStore.isReservation)(activeRunId) || activeClaimedAt !== void 0 && activeClaimedAt > now - import_TriggerStore.reservationLeaseMs) {
+    return { _tag: "Held", runId: activeRunId };
+  }
+  const occurrence = (0, import_TriggerStore.reservationOccurrence)(activeRunId);
+  if (occurrence === void 0 || unfinished === void 0) return { _tag: "Expired", expected: activeRunId };
+  const predecessor = unfinished.runId;
+  return {
+    _tag: "Expired",
+    expected: activeRunId,
+    pending: Overlap.pendingAfter({ running: false, pending, due: occurrence }),
+    ...predecessor !== void 0 && !(0, import_TriggerStore.isReservation)(predecessor) ? { recovered: predecessor } : {}
+  };
+};
+const refuse = (snapshot, fire) => {
+  if (snapshot.revision !== fire.expectedRevision) {
+    return new import_TriggerError.TriggerError({
+      code: "revision_mismatch",
+      message: `trigger ${fire.triggerId} is at revision ${snapshot.revision}, not the claimed ${fire.expectedRevision}`
+    });
+  }
+  if (!snapshot.enabled) {
+    return new import_TriggerError.TriggerError({ code: "trigger_disabled", message: `trigger ${fire.triggerId} is disabled` });
+  }
+  return void 0;
+};
+const decide = (input) => {
+  const refusal = refuse(input.snapshot, input.fire);
+  return refusal === void 0 ? decideFenced(input) : { _tag: "Refused", error: refusal };
+};
+const decideFenced = ({ claimedAt, fire, reservationId, snapshot }) => {
+  let activeRunId = snapshot.activeRunId;
+  let pending = snapshot.pending;
+  const expiredReservation = activeRunId !== void 0 && (0, import_TriggerStore.isReservation)(activeRunId) && (snapshot.activeClaimedAt === void 0 || snapshot.activeClaimedAt <= claimedAt - import_TriggerStore.reservationLeaseMs) ? activeRunId : void 0;
+  const existing = snapshot.existingFire;
+  if (existing !== void 0) {
+    const resumableBuffer = fire.resumeBuffered === true && existing.outcome === "buffered";
+    const resumableReservation = existing.outcome === null && (activeRunId === void 0 || (0, import_TriggerStore.reservationOccurrence)(activeRunId) === fire.occurrence && expiredReservation !== void 0);
+    const resumableSupersede = fire.resumeBuffered === true && existing.outcome === null && snapshot.overlap === "supersede" && activeRunId !== void 0 && existing.runId === activeRunId;
+    if (!resumableBuffer && !resumableReservation && !resumableSupersede) return decided({ claimed: false }, []);
+  }
+  const writes = [];
+  if (expiredReservation !== void 0) {
+    const expiredOccurrence = (0, import_TriggerStore.reservationOccurrence)(expiredReservation);
+    const expiredFire = expiredOccurrence === void 0 ? void 0 : snapshot.activeFire;
+    if (expiredOccurrence !== void 0 && expiredFire !== void 0 && (expiredFire.outcome === null || expiredFire.outcome === "buffered")) {
+      if (snapshot.overlap === "supersede") {
+        const predecessor = expiredFire.runId;
+        activeRunId = predecessor !== void 0 && !(0, import_TriggerStore.isReservation)(predecessor) ? predecessor : void 0;
+        if (expiredOccurrence !== fire.occurrence) {
+          writes.push({ _tag: "SetOutcome", occurrence: expiredOccurrence, outcome: "superseded", whileOpen: false });
+        }
+      } else {
+        activeRunId = void 0;
+        if (expiredOccurrence !== fire.occurrence) {
+          pending = Overlap.pendingAfter({ running: false, pending, due: expiredOccurrence });
+        }
+      }
+    } else {
+      activeRunId = void 0;
+    }
+    writes.push({ _tag: "ReleaseReservation", expected: expiredReservation, activeRunId, pending });
+  }
+  const state = { running: activeRunId !== void 0, pending, due: fire.occurrence };
+  const action = Overlap.decide(snapshot.overlap, state);
+  if (action === "skip" || action === "buffer") {
+    writes.push({
+      _tag: "SetOutcome",
+      occurrence: fire.occurrence,
+      outcome: action === "skip" ? "skipped" : "buffered",
+      whileOpen: false
+    });
+    writes.push({ _tag: "AdvanceCursor", occurrence: fire.occurrence });
+    if (action === "buffer") writes.push({ _tag: "SetPending", occurrence: Overlap.pendingAfter(state) });
+    return decided({ claimed: true, action }, writes);
+  }
+  let supersededRunId = activeRunId;
+  if (action === "supersede" && activeRunId !== void 0) {
+    if ((0, import_TriggerStore.isReservation)(activeRunId)) {
+      const activeOccurrence = (0, import_TriggerStore.reservationOccurrence)(activeRunId);
+      if (activeOccurrence !== void 0) {
+        const predecessor = snapshot.activeFire?.runId;
+        if (predecessor !== void 0 && !(0, import_TriggerStore.isReservation)(predecessor)) supersededRunId = predecessor;
+        writes.push({ _tag: "SetOutcome", occurrence: activeOccurrence, outcome: "superseded", whileOpen: true });
+      }
+    }
+    if (supersededRunId !== void 0 && !(0, import_TriggerStore.isReservation)(supersededRunId)) {
+      writes.push({ _tag: "SetRunId", occurrence: fire.occurrence, runId: supersededRunId });
+    }
+  }
+  writes.push({ _tag: "Reserve", reservationId, claimedAt });
+  return decided(
+    {
+      claimed: true,
+      action,
+      reservationId,
+      ...supersededRunId === void 0 ? {} : { activeRunId: supersededRunId }
+    },
+    writes
+  );
+};
+//# sourceMappingURL=ClaimDecision.js.map

package/dist/cjs/ClaimDecision.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ClaimDecision.ts"],
+  "sourcesContent": ["/**\n * The one claim decision both trigger stores apply.\n *\n * A claim is a pure function of the rows it reads: the trigger declaration,\n * the fire row at the occurrence being claimed, and the fire row the active\n * reservation holds. Each store gathers that snapshot in its own storage,\n * calls {@link decide}, and applies the writes it answers. Writing the fences,\n * the expired-reservation reclaim, and the supersede predecessor substitution\n * once is what keeps `SqlTriggerStore` and the published in-memory store from\n * drifting apart.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Overlap from \"./Overlap.ts\"\nimport type { Overlap as Policy } from \"./Trigger.ts\"\nimport { TriggerError } from \"./TriggerError.ts\"\nimport {\n  type Claim,\n  type ClaimFire,\n  isReservation,\n  type Outcome,\n  reservationLeaseMs,\n  reservationOccurrence\n} from \"./TriggerStore.ts\"\n\n/**\n * A fire row as the decision reads it. `outcome` is `null` for a claimed but\n * unsettled occurrence, matching the nullable column.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Fire {\n  readonly outcome: Outcome | null\n  readonly runId?: string | undefined\n}\n\n/**\n * Everything the decision reads, gathered by the store before it runs.\n *\n * `existingFire` is absent when this claim is what created the row.\n * `activeFire` is the row at `reservationOccurrence(activeRunId)`, read after\n * that insert, and is needed only while `activeRunId` is a reservation.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Snapshot {\n  readonly revision: number\n  readonly enabled: boolean\n  readonly overlap: Policy\n  readonly activeRunId?: string | undefined\n  readonly activeClaimedAt?: number | undefined\n  readonly pending?: number | undefined\n  readonly existingFire?: Fire | undefined\n  readonly activeFire?: Fire | undefined\n}\n\n/**\n * One durable edit a claim owes, in the order the store must apply them.\n *\n * `SetOutcome` with `whileOpen` may only settle a fire that is still `null` or\n * `buffered`; the SQL store spells that as a `WHERE` clause.\n * `ReleaseReservation` may only land while `expected` still owns the trigger.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Write =\n  | {\n    readonly _tag: \"SetOutcome\"\n    readonly occurrence: number\n    readonly outcome: Outcome\n    readonly whileOpen: boolean\n  }\n  | { readonly _tag: \"SetRunId\"; readonly occurrence: number; readonly runId: string }\n  | {\n    readonly _tag: \"ReleaseReservation\"\n    readonly expected: string\n    readonly activeRunId?: string | undefined\n    readonly pending?: number | undefined\n  }\n  | { readonly _tag: \"AdvanceCursor\"; readonly occurrence: number }\n  | { readonly _tag: \"SetPending\"; readonly occurrence: number }\n  | { readonly _tag: \"Reserve\"; readonly reservationId: string; readonly claimedAt: number }\n\n/**\n * What a claim decided: a refusal the store fails with, or a claim outcome and\n * the writes that make it durable. An unclaimed occurrence answers\n * `{ claimed: false }` with no writes.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Decision =\n  | { readonly _tag: \"Refused\"; readonly error: TriggerError }\n  | { readonly _tag: \"Decided\"; readonly claim: Claim; readonly writes: ReadonlyArray<Write> }\n\n/**\n * The claim request, the rows it reads, the reservation id the store minted\n * for it, and the store clock reading it was claimed at.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Input {\n  readonly fire: ClaimFire\n  readonly snapshot: Snapshot\n  readonly reservationId: string\n  readonly claimedAt: number\n}\n\ntype AdmittedDecision = Extract<Decision, { readonly _tag: \"Decided\" }>\n\nconst decided = (claim: Claim, writes: ReadonlyArray<Write>): AdmittedDecision => ({ _tag: \"Decided\", claim, writes })\n\n/**\n * What a reader finds behind a trigger's active owner: nothing, a live owner,\n * or an expired reservation to release.\n *\n * `expected` is the reservation the release must still find in place.\n * `recovered` is the launched predecessor the release hands back, and\n * `pending` is the occurrence it re-arms; both are absent when the reservation\n * covered no unsettled fire.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Lease =\n  | { readonly _tag: \"Idle\" }\n  | { readonly _tag: \"Held\"; readonly runId: string }\n  | {\n    readonly _tag: \"Expired\"\n    readonly expected: string\n    readonly recovered?: string | undefined\n    readonly pending?: number | undefined\n  }\n\n/**\n * Applies the reservation lease to a trigger's active owner.\n *\n * `unfinished` is the fire row at `reservationOccurrence(activeRunId)` while\n * that row is still `null` or `buffered`, and is absent otherwise. A process\n * that died after claiming an occurrence but before launching it left the\n * reservation; the expired lease releases it and re-arms both ordinary and\n * buffered work.\n *\n * @category decision\n * @since 1.0.0-rc.0\n */\nexport const lease = (input: {\n  readonly activeRunId?: string | undefined\n  readonly activeClaimedAt?: number | undefined\n  readonly pending?: number | undefined\n  readonly now: number\n  readonly unfinished?: Fire | undefined\n}): Lease => {\n  const { activeClaimedAt, activeRunId, now, pending, unfinished } = input\n  if (activeRunId === undefined) return { _tag: \"Idle\" }\n  if (!isReservation(activeRunId) || (activeClaimedAt !== undefined && activeClaimedAt > now - reservationLeaseMs)) {\n    return { _tag: \"Held\", runId: activeRunId }\n  }\n  const occurrence = reservationOccurrence(activeRunId)\n  if (occurrence === undefined || unfinished === undefined) return { _tag: \"Expired\", expected: activeRunId }\n  const predecessor = unfinished.runId\n  return {\n    _tag: \"Expired\",\n    expected: activeRunId,\n    pending: Overlap.pendingAfter({ running: false, pending, due: occurrence }),\n    ...(predecessor !== undefined && !isReservation(predecessor) ? { recovered: predecessor } : {})\n  }\n}\n\n/**\n * The refusals a claim owes before it reads any fire row, in the order the\n * stores apply them. A store checks these first so a refused claim leaves the\n * ledger untouched; {@link decide} re-applies them so a store that only calls\n * it is still fenced.\n *\n * @category decision\n * @since 1.0.0-rc.0\n */\nexport const refuse = (\n  snapshot: Pick<Snapshot, \"enabled\" | \"revision\">,\n  fire: ClaimFire\n): TriggerError | undefined => {\n  if (snapshot.revision !== fire.expectedRevision) {\n    return new TriggerError({\n      code: \"revision_mismatch\",\n      message: `trigger ${fire.triggerId} is at revision ${snapshot.revision}, not the claimed ${fire.expectedRevision}`\n    })\n  }\n  if (!snapshot.enabled) {\n    return new TriggerError({ code: \"trigger_disabled\", message: `trigger ${fire.triggerId} is disabled` })\n  }\n  return undefined\n}\n\n/**\n * Applies the claim protocol to a snapshot.\n *\n * @category decision\n * @since 1.0.0-rc.0\n */\nexport const decide = (input: Input): Decision => {\n  const refusal = refuse(input.snapshot, input.fire)\n  return refusal === undefined ? decideFenced(input) : { _tag: \"Refused\", error: refusal }\n}\n\n/**\n * Decides over a snapshot already admitted by {@link refuse} in the same\n * transaction. This avoids checking the same immutable revision twice.\n * @category decision\n * @since 1.0.0-rc.0\n * @private\n */\nexport const decideFenced = ({ claimedAt, fire, reservationId, snapshot }: Input): AdmittedDecision => {\n  let activeRunId = snapshot.activeRunId\n  let pending = snapshot.pending\n  // A reservation with no claim timestamp predates the lease column. Nothing\n  // writes that shape now, so treating it as expired is the only way such a\n  // row is ever reclaimed.\n  const expiredReservation = activeRunId !== undefined && isReservation(activeRunId) &&\n      (snapshot.activeClaimedAt === undefined || snapshot.activeClaimedAt <= claimedAt - reservationLeaseMs)\n    ? activeRunId\n    : undefined\n  const existing = snapshot.existingFire\n  if (existing !== undefined) {\n    const resumableBuffer = fire.resumeBuffered === true && existing.outcome === \"buffered\"\n    const resumableReservation = existing.outcome === null &&\n      (activeRunId === undefined ||\n        (reservationOccurrence(activeRunId) === fire.occurrence && expiredReservation !== undefined))\n    const resumableSupersede = fire.resumeBuffered === true && existing.outcome === null &&\n      snapshot.overlap === \"supersede\" && activeRunId !== undefined && existing.runId === activeRunId\n    if (!resumableBuffer && !resumableReservation && !resumableSupersede) return decided({ claimed: false }, [])\n  }\n  const writes: Array<Write> = []\n  if (expiredReservation !== undefined) {\n    const expiredOccurrence = reservationOccurrence(expiredReservation)\n    const expiredFire = expiredOccurrence === undefined ? undefined : snapshot.activeFire\n    if (\n      expiredOccurrence !== undefined && expiredFire !== undefined &&\n      (expiredFire.outcome === null || expiredFire.outcome === \"buffered\")\n    ) {\n      if (snapshot.overlap === \"supersede\") {\n        const predecessor = expiredFire.runId\n        activeRunId = predecessor !== undefined && !isReservation(predecessor) ? predecessor : undefined\n        if (expiredOccurrence !== fire.occurrence) {\n          writes.push({ _tag: \"SetOutcome\", occurrence: expiredOccurrence, outcome: \"superseded\", whileOpen: false })\n        }\n      } else {\n        activeRunId = undefined\n        if (expiredOccurrence !== fire.occurrence) {\n          pending = Overlap.pendingAfter({ running: false, pending, due: expiredOccurrence })\n        }\n      }\n    } else {\n      activeRunId = undefined\n    }\n    writes.push({ _tag: \"ReleaseReservation\", expected: expiredReservation, activeRunId, pending })\n  }\n  const state: Overlap.State = { running: activeRunId !== undefined, pending, due: fire.occurrence }\n  const action = Overlap.decide(snapshot.overlap, state)\n  // A skip or buffer is complete inside the claim transaction. A fire or\n  // supersede is only reserved here; its cursor advances when `recordResult`\n  // makes the launched run durable.\n  if (action === \"skip\" || action === \"buffer\") {\n    writes.push({\n      _tag: \"SetOutcome\",\n      occurrence: fire.occurrence,\n      outcome: action === \"skip\" ? \"skipped\" : \"buffered\",\n      whileOpen: false\n    })\n    writes.push({ _tag: \"AdvanceCursor\", occurrence: fire.occurrence })\n    if (action === \"buffer\") writes.push({ _tag: \"SetPending\", occurrence: Overlap.pendingAfter(state) })\n    return decided({ claimed: true, action }, writes)\n  }\n  let supersededRunId = activeRunId\n  if (action === \"supersede\" && activeRunId !== undefined) {\n    if (isReservation(activeRunId)) {\n      const activeOccurrence = reservationOccurrence(activeRunId)\n      if (activeOccurrence !== undefined) {\n        const predecessor = snapshot.activeFire?.runId\n        if (predecessor !== undefined && !isReservation(predecessor)) supersededRunId = predecessor\n        writes.push({ _tag: \"SetOutcome\", occurrence: activeOccurrence, outcome: \"superseded\", whileOpen: true })\n      }\n    }\n    if (supersededRunId !== undefined && !isReservation(supersededRunId)) {\n      writes.push({ _tag: \"SetRunId\", occurrence: fire.occurrence, runId: supersededRunId })\n    }\n  }\n  writes.push({ _tag: \"Reserve\", reservationId, claimedAt })\n  return decided(\n    {\n      claimed: true,\n      action,\n      reservationId,\n      ...(supersededRunId === undefined ? {} : { activeRunId: supersededRunId })\n    },\n    writes\n  )\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/Cron.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Typed wrappers around Effect Cron.
+ *
+ * Effect's field parser only range-checks each field, so an expression like
+ * `0 0 30 2 *` parses and then never matches a calendar date. Its occurrence
+ * search answers that by exhausting its bound and throwing, which inside
+ * `Effect.gen` is a defect rather than a typed failure: the fiber that owns the
+ * search dies instead of reporting. Every search here is wrapped so the
+ * exhausted bound arrives as `unsatisfiable_cron`, and {@link parse} probes for
+ * one occurrence so an unsatisfiable expression is refused where it is
+ * declared rather than at the tick that would have fired it.
+ *
+ * A satisfiable expression carries the opposite hazard: `* * * * *` across a
+ * year is 525,600 occurrences, and materializing them costs seconds and
+ * hundreds of megabytes. {@link occurrencesBetween} therefore always searches
+ * under a finite cap and reports when an unstated limit would exceed
+ * {@link maxOccurrences}.
+ *
+ * A timezone makes the expression a wall-clock schedule. A wall time that
+ * spring forward skips fires at the instant it would have had on the old
+ * offset, so a daily 02:30 fires at 03:30 daylight time. A wall time that fall
+ * back repeats fires once, at its first instant, unless the hour field is every
+ * hour, in which case both passes fire. Occurrences are whole seconds in UTC,
+ * whatever the host's zone.
+ *
+ * @since 0.1.0
+ */
+import * as EffectCron from "effect/Cron";
+import * as Effect from "effect/Effect";
+import { TriggerError } from "./TriggerError.ts";
+/**
+ * A parsed cron expression, kept beside the text it came from so the
+ * declaration can be round-tripped.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Cron {
+    readonly expression: string;
+    readonly timezone?: string | undefined;
+    readonly value: EffectCron.Cron;
+}
+/**
+ * The first occurrence strictly after `from`.
+ *
+ * @category getters
+ * @since 0.1.0
+ */
+export declare const next: (cron: Cron, from: Date) => Effect.Effect<Date, TriggerError>;
+/**
+ * Returns the latest occurrence at or before `at`.
+ *
+ * @category getters
+ * @since 0.1.0
+ */
+export declare const previousAtOrBefore: (cron: Cron, at: Date) => Effect.Effect<Date, TriggerError>;
+/**
+ * The greatest number of occurrences one search returns when its caller states
+ * no limit of its own.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const maxOccurrences = 1000;
+/**
+ * The occurrences in `(from, to]`, in order.
+ *
+ * A stated `limit` caps the result silently and must be a non-negative safe
+ * integer. With no stated limit, the search fails with
+ * `catch_up_bound_exceeded` when the interval holds more than
+ * {@link maxOccurrences}. A caller with its own bound can pass one more than
+ * that bound and compare the length, the way `CatchUp.occurrences` does.
+ *
+ * @category sequencing
+ * @since 0.1.0
+ */
+export declare const occurrencesBetween: (cron: Cron, from: Date, to: Date, limit?: number | undefined) => Effect.Effect<ReadonlyArray<Date>, TriggerError>;
+/**
+ * Parses a cron expression in an optional timezone, reporting a malformed one
+ * as `invalid_cron` and one the calendar never satisfies as
+ * `unsatisfiable_cron`.
+ *
+ * The satisfiability probe searches forward from the current instant, which is
+ * the same search every tick performs, so an expression that survives parsing
+ * is one the scheduler can keep answering.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const parse: (expression: string, timezone?: string) => Effect.Effect<Cron, TriggerError>;
+//# sourceMappingURL=Cron.d.ts.map

package/dist/cjs/Cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cron.d.ts","sourceRoot":"","sources":["../../src/Cron.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,UAAU,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,CAAA;CAChC;AAYD;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,IAAI,EAAE,MAAM,IAAI,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CACwB,CAAA;AAEtG;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,IAAI,EAAE,IAAI,IAAI,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAKvF,CAAA;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,OAAO,CAAA;AAElC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,GAC7B,MAAM,IAAI,EACV,MAAM,IAAI,EACV,IAAI,IAAI,EACR,QAAQ,MAAM,GAAG,SAAS,KACzB,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,YAAY,CAoCjD,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,GAAI,YAAY,MAAM,EAAE,WAAW,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAgB1F,CAAA"}

package/dist/cjs/Cron.js

@@ -0,0 +1,108 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Cron_exports = {};
+__export(Cron_exports, {
+  maxOccurrences: () => maxOccurrences,
+  next: () => next,
+  occurrencesBetween: () => occurrencesBetween,
+  parse: () => parse,
+  previousAtOrBefore: () => previousAtOrBefore
+});
+module.exports = __toCommonJS(Cron_exports);
+var Clock = __toESM(require("effect/Clock"), 1);
+var EffectCron = __toESM(require("effect/Cron"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Result = __toESM(require("effect/Result"), 1);
+var WallClock = __toESM(require("./internal/WallClock.js"), 1);
+var import_TriggerError = require("./TriggerError.js");
+const exhausted = (cron, search, cause) => new import_TriggerError.TriggerError({
+  code: "unsatisfiable_cron",
+  message: `cron expression '${cron.expression}' has no ${search} occurrence`,
+  cause
+});
+const attempt = (cron, search, find) => Effect.try({ try: find, catch: (cause) => exhausted(cron, search, cause) });
+const next = (cron, from) => attempt(cron, "next", () => new Date(WallClock.next(WallClock.compile(cron.value), from.getTime())));
+const previousAtOrBefore = (cron, at) => attempt(
+  cron,
+  "previous",
+  () => new Date(WallClock.previousAtOrBefore(WallClock.compile(cron.value), at.getTime()))
+);
+const maxOccurrences = 1e3;
+const occurrencesBetween = (cron, from, to, limit) => {
+  if (limit !== void 0 && (!Number.isSafeInteger(limit) || limit < 0)) {
+    return Effect.fail(
+      new import_TriggerError.TriggerError({
+        code: "invalid_options",
+        message: `occurrence limit must be a non-negative safe integer, received ${limit}`,
+        path: "limit"
+      })
+    );
+  }
+  const searchLimit = limit ?? maxOccurrences + 1;
+  if (searchLimit === 0) return Effect.succeed([]);
+  const search = attempt(cron, "interval", () => {
+    const wall = WallClock.compile(cron.value);
+    const occurrences = [];
+    let cursor = from.getTime();
+    while (occurrences.length < searchLimit) {
+      cursor = WallClock.next(wall, cursor);
+      if (cursor > to.getTime()) break;
+      occurrences.push(new Date(cursor));
+    }
+    return occurrences;
+  });
+  if (limit !== void 0) return search;
+  return search.pipe(
+    Effect.flatMap(
+      (occurrences) => occurrences.length > maxOccurrences ? Effect.fail(
+        new import_TriggerError.TriggerError({
+          code: "catch_up_bound_exceeded",
+          message: `interval contains more than ${maxOccurrences} occurrences; maxOccurrences is ${maxOccurrences}`
+        })
+      ) : Effect.succeed(occurrences)
+    )
+  );
+};
+const parse = (expression, timezone) => Effect.gen(function* () {
+  const parsed = EffectCron.parse(expression, timezone);
+  if (Result.isFailure(parsed)) {
+    return yield* Effect.fail(
+      new import_TriggerError.TriggerError({ code: "invalid_cron", message: parsed.failure.message, cause: parsed.failure })
+    );
+  }
+  const cron = {
+    expression,
+    ...timezone === void 0 ? {} : { timezone },
+    value: parsed.success
+  };
+  const now = yield* Clock.currentTimeMillis;
+  yield* next(cron, new Date(now));
+  return cron;
+});
+//# sourceMappingURL=Cron.js.map

package/dist/cjs/Cron.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Cron.ts"],
+  "sourcesContent": ["/**\n * Typed wrappers around Effect Cron.\n *\n * Effect's field parser only range-checks each field, so an expression like\n * `0 0 30 2 *` parses and then never matches a calendar date. Its occurrence\n * search answers that by exhausting its bound and throwing, which inside\n * `Effect.gen` is a defect rather than a typed failure: the fiber that owns the\n * search dies instead of reporting. Every search here is wrapped so the\n * exhausted bound arrives as `unsatisfiable_cron`, and {@link parse} probes for\n * one occurrence so an unsatisfiable expression is refused where it is\n * declared rather than at the tick that would have fired it.\n *\n * A satisfiable expression carries the opposite hazard: `* * * * *` across a\n * year is 525,600 occurrences, and materializing them costs seconds and\n * hundreds of megabytes. {@link occurrencesBetween} therefore always searches\n * under a finite cap and reports when an unstated limit would exceed\n * {@link maxOccurrences}.\n *\n * A timezone makes the expression a wall-clock schedule. A wall time that\n * spring forward skips fires at the instant it would have had on the old\n * offset, so a daily 02:30 fires at 03:30 daylight time. A wall time that fall\n * back repeats fires once, at its first instant, unless the hour field is every\n * hour, in which case both passes fire. Occurrences are whole seconds in UTC,\n * whatever the host's zone.\n *\n * @since 0.1.0\n */\n\nimport * as Clock from \"effect/Clock\"\nimport * as EffectCron from \"effect/Cron\"\nimport * as Effect from \"effect/Effect\"\nimport * as Result from \"effect/Result\"\nimport * as WallClock from \"./internal/WallClock.ts\"\nimport { TriggerError } from \"./TriggerError.ts\"\n\n/**\n * A parsed cron expression, kept beside the text it came from so the\n * declaration can be round-tripped.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Cron {\n  readonly expression: string\n  readonly timezone?: string | undefined\n  readonly value: EffectCron.Cron\n}\n\nconst exhausted = (cron: Cron, search: string, cause: unknown): TriggerError =>\n  new TriggerError({\n    code: \"unsatisfiable_cron\",\n    message: `cron expression '${cron.expression}' has no ${search} occurrence`,\n    cause\n  })\n\nconst attempt = <A>(cron: Cron, search: string, find: () => A): Effect.Effect<A, TriggerError> =>\n  Effect.try({ try: find, catch: (cause) => exhausted(cron, search, cause) })\n\n/**\n * The first occurrence strictly after `from`.\n *\n * @category getters\n * @since 0.1.0\n */\nexport const next = (cron: Cron, from: Date): Effect.Effect<Date, TriggerError> =>\n  attempt(cron, \"next\", () => new Date(WallClock.next(WallClock.compile(cron.value), from.getTime())))\n\n/**\n * Returns the latest occurrence at or before `at`.\n *\n * @category getters\n * @since 0.1.0\n */\nexport const previousAtOrBefore = (cron: Cron, at: Date): Effect.Effect<Date, TriggerError> =>\n  attempt(\n    cron,\n    \"previous\",\n    () => new Date(WallClock.previousAtOrBefore(WallClock.compile(cron.value), at.getTime()))\n  )\n\n/**\n * The greatest number of occurrences one search returns when its caller states\n * no limit of its own.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const maxOccurrences = 1000\n\n/**\n * The occurrences in `(from, to]`, in order.\n *\n * A stated `limit` caps the result silently and must be a non-negative safe\n * integer. With no stated limit, the search fails with\n * `catch_up_bound_exceeded` when the interval holds more than\n * {@link maxOccurrences}. A caller with its own bound can pass one more than\n * that bound and compare the length, the way `CatchUp.occurrences` does.\n *\n * @category sequencing\n * @since 0.1.0\n */\nexport const occurrencesBetween = (\n  cron: Cron,\n  from: Date,\n  to: Date,\n  limit?: number | undefined\n): Effect.Effect<ReadonlyArray<Date>, TriggerError> => {\n  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0)) {\n    return Effect.fail(\n      new TriggerError({\n        code: \"invalid_options\",\n        message: `occurrence limit must be a non-negative safe integer, received ${limit}`,\n        path: \"limit\"\n      })\n    )\n  }\n  const searchLimit = limit ?? maxOccurrences + 1\n  if (searchLimit === 0) return Effect.succeed([])\n  const search = attempt(cron, \"interval\", () => {\n    const wall = WallClock.compile(cron.value)\n    const occurrences: Array<Date> = []\n    let cursor = from.getTime()\n    while (occurrences.length < searchLimit) {\n      cursor = WallClock.next(wall, cursor)\n      if (cursor > to.getTime()) break\n      occurrences.push(new Date(cursor))\n    }\n    return occurrences\n  })\n  if (limit !== undefined) return search\n  return search.pipe(\n    Effect.flatMap((occurrences) =>\n      occurrences.length > maxOccurrences\n        ? Effect.fail(\n          new TriggerError({\n            code: \"catch_up_bound_exceeded\",\n            message: `interval contains more than ${maxOccurrences} occurrences; maxOccurrences is ${maxOccurrences}`\n          })\n        )\n        : Effect.succeed(occurrences)\n    )\n  )\n}\n\n/**\n * Parses a cron expression in an optional timezone, reporting a malformed one\n * as `invalid_cron` and one the calendar never satisfies as\n * `unsatisfiable_cron`.\n *\n * The satisfiability probe searches forward from the current instant, which is\n * the same search every tick performs, so an expression that survives parsing\n * is one the scheduler can keep answering.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const parse = (expression: string, timezone?: string): Effect.Effect<Cron, TriggerError> =>\n  Effect.gen(function*() {\n    const parsed = EffectCron.parse(expression, timezone)\n    if (Result.isFailure(parsed)) {\n      return yield* Effect.fail(\n        new TriggerError({ code: \"invalid_cron\", message: parsed.failure.message, cause: parsed.failure })\n      )\n    }\n    const cron: Cron = {\n      expression,\n      ...(timezone === undefined ? {} : { timezone }),\n      value: parsed.success\n    }\n    const now = yield* Clock.currentTimeMillis\n    yield* next(cron, new Date(now))\n    return cron\n  })\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4BA,YAAuB;AACvB,iBAA4B;AAC5B,aAAwB;AACxB,aAAwB;AACxB,gBAA2B;AAC3B,0BAA6B;AAe7B,MAAM,YAAY,CAAC,MAAY,QAAgB,UAC7C,IAAI,iCAAa;AAAA,EACf,MAAM;AAAA,EACN,SAAS,oBAAoB,KAAK,UAAU,YAAY,MAAM;AAAA,EAC9D;AACF,CAAC;AAEH,MAAM,UAAU,CAAI,MAAY,QAAgB,SAC9C,OAAO,IAAI,EAAE,KAAK,MAAM,OAAO,CAAC,UAAU,UAAU,MAAM,QAAQ,KAAK,EAAE,CAAC;AAQrE,MAAM,OAAO,CAAC,MAAY,SAC/B,QAAQ,MAAM,QAAQ,MAAM,IAAI,KAAK,UAAU,KAAK,UAAU,QAAQ,KAAK,KAAK,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC;AAQ9F,MAAM,qBAAqB,CAAC,MAAY,OAC7C;AAAA,EACE;AAAA,EACA;AAAA,EACA,MAAM,IAAI,KAAK,UAAU,mBAAmB,UAAU,QAAQ,KAAK,KAAK,GAAG,GAAG,QAAQ,CAAC,CAAC;AAC1F;AASK,MAAM,iBAAiB;AAcvB,MAAM,qBAAqB,CAChC,MACA,MACA,IACA,UACqD;AACrD,MAAI,UAAU,WAAc,CAAC,OAAO,cAAc,KAAK,KAAK,QAAQ,IAAI;AACtE,WAAO,OAAO;AAAA,MACZ,IAAI,iCAAa;AAAA,QACf,MAAM;AAAA,QACN,SAAS,kEAAkE,KAAK;AAAA,QAChF,MAAM;AAAA,MACR,CAAC;AAAA,IACH;AAAA,EACF;AACA,QAAM,cAAc,SAAS,iBAAiB;AAC9C,MAAI,gBAAgB,EAAG,QAAO,OAAO,QAAQ,CAAC,CAAC;AAC/C,QAAM,SAAS,QAAQ,MAAM,YAAY,MAAM;AAC7C,UAAM,OAAO,UAAU,QAAQ,KAAK,KAAK;AACzC,UAAM,cAA2B,CAAC;AAClC,QAAI,SAAS,KAAK,QAAQ;AAC1B,WAAO,YAAY,SAAS,aAAa;AACvC,eAAS,UAAU,KAAK,MAAM,MAAM;AACpC,UAAI,SAAS,GAAG,QAAQ,EAAG;AAC3B,kBAAY,KAAK,IAAI,KAAK,MAAM,CAAC;AAAA,IACnC;AACA,WAAO;AAAA,EACT,CAAC;AACD,MAAI,UAAU,OAAW,QAAO;AAChC,SAAO,OAAO;AAAA,IACZ,OAAO;AAAA,MAAQ,CAAC,gBACd,YAAY,SAAS,iBACjB,OAAO;AAAA,QACP,IAAI,iCAAa;AAAA,UACf,MAAM;AAAA,UACN,SAAS,+BAA+B,cAAc,mCAAmC,cAAc;AAAA,QACzG,CAAC;AAAA,MACH,IACE,OAAO,QAAQ,WAAW;AAAA,IAChC;AAAA,EACF;AACF;AAcO,MAAM,QAAQ,CAAC,YAAoB,aACxC,OAAO,IAAI,aAAY;AACrB,QAAM,SAAS,WAAW,MAAM,YAAY,QAAQ;AACpD,MAAI,OAAO,UAAU,MAAM,GAAG;AAC5B,WAAO,OAAO,OAAO;AAAA,MACnB,IAAI,iCAAa,EAAE,MAAM,gBAAgB,SAAS,OAAO,QAAQ,SAAS,OAAO,OAAO,QAAQ,CAAC;AAAA,IACnG;AAAA,EACF;AACA,QAAM,OAAa;AAAA,IACjB;AAAA,IACA,GAAI,aAAa,SAAY,CAAC,IAAI,EAAE,SAAS;AAAA,IAC7C,OAAO,OAAO;AAAA,EAChB;AACA,QAAM,MAAM,OAAO,MAAM;AACzB,SAAO,KAAK,MAAM,IAAI,KAAK,GAAG,CAAC;AAC/B,SAAO;AACT,CAAC;",
+  "names": []
+}