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

package/dist/cjs/TriggerStore.d.ts

@@ -0,0 +1,411 @@
+/**
+ * Durable trigger declaration and fire store.
+ *
+ * @see packages/smithers/agent/triggers/docs/api.md
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Option from "effect/Option";
+import * as Decode from "effect/Result";
+import type { Action } from "./Overlap.ts";
+import type { Trigger } from "./Trigger.ts";
+import { TriggerError } from "./TriggerError.ts";
+/**
+ * A stored trigger, with the revision that fences concurrent edits and
+ * when it last fired.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Registered extends Trigger {
+    readonly revision: number;
+    readonly lastFiredAt?: number | undefined;
+}
+/**
+ * One scheduled occurrence of a trigger, addressed by its occurrence
+ * number so a retry cannot fire it twice.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Fire {
+    readonly triggerId: string;
+    readonly occurrence: number;
+}
+/**
+ * A {@link Fire} together with the revision it was computed from and whether
+ * it is resuming a buffered occurrence.
+ *
+ * The overlap policy is deliberately absent. A claim applies the policy stored
+ * on the trigger row, read inside the same transaction, so a caller holding a
+ * stale snapshot cannot fire a trigger that has since been disabled, cannot
+ * point it at a different flow, and cannot supersede a run that the stored
+ * declaration says to leave alone. `expectedRevision` is the fence: a claim
+ * whose revision no longer matches the row is refused with `revision_mismatch`
+ * so the caller re-reads before deciding again.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface ClaimFire extends Fire {
+    readonly expectedRevision: number;
+    readonly resumeBuffered?: boolean | undefined;
+}
+/**
+ * The outcome of claiming an occurrence: either another worker holds it, or
+ * this caller does and must take `action`.
+ *
+ * A claim that hands the caller work to launch always names the reservation it
+ * wrote against the trigger row, so the caller has an id to release. A claim
+ * that only records a decision has no reservation and names none: the two
+ * shapes are separate so a caller cannot read a reservation id that was never
+ * written.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Claim = {
+    readonly claimed: false;
+} | {
+    readonly claimed: true;
+    readonly action: Extract<Action, "skip" | "buffer">;
+} | {
+    readonly claimed: true;
+    readonly action: Extract<Action, "fire" | "supersede">;
+    readonly reservationId: string;
+    readonly activeRunId?: string | undefined;
+};
+/**
+ * Time after which an uncommitted launch reservation may be reclaimed.
+ *
+ * Both store implementations use this value so swapping the test store for
+ * the SQL store cannot change recovery timing.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const reservationLeaseMs: number;
+/**
+ * The prefix marking an `active_run_id` that is a launch reservation rather
+ * than a run the runtime knows about.
+ *
+ * A reservation is written by the claim and replaced by the real run id once
+ * the launch reports one, so both stores and the scheduler read this prefix.
+ * It is a contract between them and lives here rather than being re-spelled at
+ * each site.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const reservationPrefix = "trigger-reservation:";
+/**
+ * The reservation id one occurrence of one trigger claims.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const reservationId: (triggerId: string, occurrence: number, attempt?: string) => string;
+/**
+ * Whether a stored `active_run_id` is a launch reservation.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export declare const isReservation: (runId: string | undefined) => boolean;
+/**
+ * Reads the occurrence encoded in a launch reservation.
+ *
+ * @category getters
+ * @since 0.1.0
+ */
+export declare const reservationOccurrence: (runId: string) => number | undefined;
+/**
+ * How a claimed occurrence ended.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Outcome = "launched" | "completed" | "skipped" | "buffered" | "superseded" | "failed";
+/**
+ * The reported end of one occurrence, with the run it started when it
+ * launched one.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Result = Fire & {
+    readonly error?: string | undefined;
+} & ({
+    readonly outcome: "launched";
+    readonly runId: string;
+    readonly reservationId: string;
+} | {
+    readonly outcome: Exclude<Outcome, "launched">;
+    readonly runId?: string | undefined;
+    readonly reservationId?: string | undefined;
+});
+/**
+ * Refuses results that no longer own a permissible fire transition.
+ * Launched run ids are validated at runtime for adapters outside TypeScript.
+ *
+ * @category predicates
+ * @since 1.0.0-rc.0
+ */
+export declare const resultRefusal: (result: Result, fire: FireRecord | undefined, activeRunId: string | undefined) => TriggerError | undefined;
+/**
+ * One row of the fire ledger: a claimed occurrence and what became of it.
+ *
+ * `outcome` is `null` between a claim and its `recordResult`, the window in
+ * which a launch is reserved but not yet reported.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface FireRecord extends Fire {
+    readonly outcome: Outcome | null;
+    readonly runId?: string | undefined;
+    readonly error?: string | undefined;
+}
+/**
+ * A ledger query. Every filter narrows; `cursor` is the last record of the
+ * previous page, so the page after it holds only older records; `limit` caps
+ * a page and must be a positive safe integer when stated. With no limit the
+ * whole ledger answers in one page.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface HistoryQuery {
+    readonly triggerId?: string | undefined;
+    readonly runId?: string | undefined;
+    readonly outcome?: Outcome | undefined;
+    readonly cursor?: Fire | undefined;
+    readonly limit?: number | undefined;
+}
+/**
+ * One page of the ledger, newest occurrence first, with the cursor that
+ * addresses the next page when the limit cut the page short.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface HistoryPage {
+    readonly items: ReadonlyArray<FireRecord>;
+    readonly nextCursor?: Fire | undefined;
+}
+/**
+ * What one trigger holds right now: the run or launch reservation on its row
+ * and the occurrence buffered behind it. A plain read; `activeRun` is the read
+ * that expires a stale reservation.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Held {
+    readonly activeRunId?: string | undefined;
+    readonly pendingAt?: number | undefined;
+}
+/**
+ * One row of a listing: what the trigger holds right now, and either the
+ * declaration the row decoded to or the failure it could not be read through.
+ *
+ * `trigger` is an `effect/Result`: narrow it with `Result.isFailure` before
+ * reading the declaration. An undecodable row is isolated here rather than
+ * failing the whole listing,
+ * so one corrupt input cannot stop every other trigger from being scheduled.
+ * The held state travels with the row because a scheduler tick would otherwise
+ * ask for it again per trigger, once to expire a reservation that is not there
+ * and once for a buffered occurrence that is not there either.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Listed extends Held {
+    readonly triggerId: string;
+    readonly trigger: Decode.Result<Registered, TriggerError>;
+}
+/**
+ * A listed row for a declaration that decoded, holding what the trigger holds
+ * right now. Both stores build their rows through this, so a caller composing
+ * a store or a scheduler fixture of its own does not restate the shape.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const listed: (trigger: Registered, held?: Held) => Listed;
+/**
+ * The last poll one scheduler host recorded.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Heartbeat {
+    readonly host: string;
+    readonly tickedAt: number;
+}
+/**
+ * Validates a {@link HistoryQuery} limit: absent, or a positive safe integer.
+ * Both stores apply this before reading so swapping one for the other cannot
+ * change which queries are refused.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const historyLimit: (limit: number | undefined) => Effect.Effect<number | undefined, TriggerError>;
+/**
+ * Validates a prune cutoff: any safe integer. Both stores apply this before
+ * deleting so swapping one for the other cannot change which cutoffs are
+ * refused.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const pruneCutoff: (olderThan: number) => Effect.Effect<number, TriggerError>;
+/**
+ * Newest occurrence first; equal occurrences of different triggers order by
+ * descending trigger id so a cursor names one position.
+ *
+ * @category ordering
+ * @since 1.0.0-rc.0
+ */
+export declare const compareNewestFirst: (left: Fire, right: Fire) => number;
+/**
+ * Whether a record lies after `cursor` in {@link compareNewestFirst} order.
+ *
+ * @category predicates
+ * @since 1.0.0-rc.0
+ */
+export declare const isAfterCursor: (record: Fire, cursor: Fire) => boolean;
+/**
+ * Cuts an ordered, filtered record list to one page. The caller fetches one
+ * record past the limit; that record's presence is what says a next page
+ * exists, and the page's last record is the cursor addressing it.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const historyPage: (records: ReadonlyArray<FireRecord>, limit: number | undefined) => HistoryPage;
+/**
+ * Durable trigger state: registration, listing, and the claim protocol that
+ * keeps two schedulers from firing the same occurrence.
+ *
+ * Neither listing is a due-time query. Due-ness is a cron computation the
+ * scheduler performs against its own watermark, so the store is asked only for
+ * the rows eligible to be considered. A scheduler tick reads `list`, not
+ * `listEnabled`: a disabled trigger can still hold an active occurrence that
+ * has to recover, and the tick skips only its new claims. `listEnabled`
+ * answers the narrower question for a caller that wants the declarations.
+ *
+ * A claim, result, pending-state, or active-run method fails with
+ * `unknown_trigger` when the row it addresses does not exist. `get` answers
+ * `None` for an absent row and `register` creates one. `clearActive` is a
+ * compare-and-swap that cannot tell a missing trigger from a run id that no
+ * longer matches, so it stays a no-op for both. `history`, `pruneFires`,
+ * `heartbeat`, and `lastHeartbeat` address the whole store.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    readonly register: (trigger: Trigger) => Effect.Effect<Registered, TriggerError>;
+    readonly get: (triggerId: string) => Effect.Effect<Option.Option<Registered>, TriggerError>;
+    /**
+     * Every trigger, enabled or not, ordered by id. This is what a scheduler
+     * tick polls: see {@link Listed} for why a row carries its decode result and
+     * its held state rather than a bare declaration.
+     */
+    readonly list: () => Effect.Effect<ReadonlyArray<Listed>, TriggerError>;
+    readonly listEnabled: () => Effect.Effect<ReadonlyArray<Registered>, TriggerError>;
+    readonly claimFire: (fire: ClaimFire) => Effect.Effect<Claim, TriggerError>;
+    /**
+     * Claims the buffered occurrence, when one exists.
+     *
+     * One transaction reads the occurrence, applies the same claim protocol as
+     * {@link Service.claimFire}, and clears the buffer only when the decision
+     * consumes it. A concurrent buffer decision keeps it pending. No failure can
+     * land between reading the buffer and claiming it.
+     */
+    readonly claimPending: (fire: {
+        readonly triggerId: string;
+        readonly expectedRevision: number;
+    }) => Effect.Effect<Option.Option<{
+        readonly occurrence: number;
+        readonly claim: Claim;
+    }>, TriggerError>;
+    readonly recordResult: (result: Result) => Effect.Effect<void, TriggerError>;
+    /** Atomically re-arms unfinished work and releases only its matching reservation.
+     * A retained predecessor is restored with the pending pointer in the same write.
+     * A stale token fails with `stale_owner`; a failed write leaves the lease intact.
+     */
+    readonly restorePending: (fire: Fire & {
+        readonly reservationId: string;
+    }) => Effect.Effect<void, TriggerError>;
+    readonly setPending: (fire: Fire) => Effect.Effect<void, TriggerError>;
+    readonly activeRun: (triggerId: string) => Effect.Effect<Option.Option<string>, TriggerError>;
+    /**
+     * Returns the occurrence owned by one active run or launch reservation.
+     *
+     * `lastFiredAt` cannot answer this: later skipped and buffered occurrences
+     * advance that cursor while an older run remains active.
+     */
+    readonly activeOccurrence: (triggerId: string, runId: string) => Effect.Effect<Option.Option<number>, TriggerError>;
+    readonly clearActive: (triggerId: string, runId: string) => Effect.Effect<void, TriggerError>;
+    /**
+     * Reads the fire ledger newest first. See {@link HistoryQuery} for the
+     * filters and paging contract; a limit that is not a positive safe integer
+     * is refused with `invalid_options`.
+     */
+    readonly history: (query?: HistoryQuery) => Effect.Effect<HistoryPage, TriggerError>;
+    /**
+     * Deletes settled fire ledger rows older than `olderThan`, answering how
+     * many it removed. Nothing else in the store deletes from the ledger, so a
+     * host that never calls this keeps one row per occurrence forever.
+     *
+     * A row is settled when its outcome is `completed`, `failed`, `skipped`, or
+     * `superseded`. The occurrence a trigger currently buffers and the row
+     * naming its active run are kept whatever their age, so pruning cannot take
+     * state the scheduler still reads. `olderThan` that is not a safe integer is
+     * refused with `invalid_options`.
+     */
+    readonly pruneFires: (options: {
+        readonly olderThan: number;
+    }) => Effect.Effect<number, TriggerError>;
+    /**
+     * Reads what one trigger holds without expiring anything, so a listing can
+     * report a reservation or a buffered occurrence exactly as the row has it.
+     */
+    readonly inspect: (triggerId: string) => Effect.Effect<Held, TriggerError>;
+    /** Records that `host` polled the store at the store clock's current time. */
+    readonly heartbeat: (host: string) => Effect.Effect<void, TriggerError>;
+    /** The most recent heartbeat across every host, or `None` when no scheduler has ever polled. */
+    readonly lastHeartbeat: () => Effect.Effect<Option.Option<Heartbeat>, TriggerError>;
+}
+declare const TriggerStore_base: Context.ServiceClass<TriggerStore, "flows/triggers/TriggerStore", Service>;
+/**
+ * The {@link Service} tag.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class TriggerStore extends TriggerStore_base {
+}
+/**
+ * A {@link Service} that fails every method as unavailable, for an
+ * environment with no trigger store. Overrides replace individual methods.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: (overrides?: Partial<Service>) => Layer.Layer<TriggerStore>;
+export {};
+//# sourceMappingURL=TriggerStore.d.ts.map

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

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

package/dist/cjs/TriggerStore.js

@@ -0,0 +1,127 @@
+"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 TriggerStore_exports = {};
+__export(TriggerStore_exports, {
+  TriggerStore: () => TriggerStore,
+  compareNewestFirst: () => compareNewestFirst,
+  historyLimit: () => historyLimit,
+  historyPage: () => historyPage,
+  isAfterCursor: () => isAfterCursor,
+  isReservation: () => isReservation,
+  layerNoop: () => layerNoop,
+  listed: () => listed,
+  makeNoop: () => makeNoop,
+  pruneCutoff: () => pruneCutoff,
+  reservationId: () => reservationId,
+  reservationLeaseMs: () => reservationLeaseMs,
+  reservationOccurrence: () => reservationOccurrence,
+  reservationPrefix: () => reservationPrefix,
+  resultRefusal: () => resultRefusal
+});
+module.exports = __toCommonJS(TriggerStore_exports);
+var Context = __toESM(require("effect/Context"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Layer = __toESM(require("effect/Layer"), 1);
+var Decode = __toESM(require("effect/Result"), 1);
+var import_TriggerError = require("./TriggerError.js");
+const reservationLeaseMs = 5 * 60 * 1e3;
+const reservationPrefix = "trigger-reservation:";
+const reservationId = (triggerId, occurrence, attempt) => `${reservationPrefix}${triggerId}:${attempt === void 0 ? "" : `${attempt}:`}${occurrence}`;
+const isReservation = (runId) => runId !== void 0 && runId.startsWith(reservationPrefix);
+const reservationOccurrence = (runId) => {
+  if (!isReservation(runId)) return void 0;
+  const occurrence = Number(runId.slice(runId.lastIndexOf(":") + 1));
+  return Number.isFinite(occurrence) ? occurrence : void 0;
+};
+const resultRefusal = (result, fire, activeRunId) => {
+  if (result.outcome === "launched" && (typeof result.runId !== "string" || result.runId.trim().length === 0)) {
+    return new import_TriggerError.TriggerError({ code: "invalid_options", message: "launched requires a non-empty runId", path: "runId" });
+  }
+  const unfinished = fire?.outcome === null || fire?.outcome === "buffered";
+  const reservation = activeRunId !== void 0 && isReservation(activeRunId) && reservationOccurrence(activeRunId) === result.occurrence;
+  const owner = result.reservationId ?? result.runId ?? (reservation ? activeRunId : void 0);
+  const permitted = result.outcome === "launched" ? unfinished && reservation && result.reservationId === activeRunId : fire !== void 0 && // A repeated decision or settlement is harmless; callers do not rewrite it.
+  (fire.outcome === result.outcome && (result.runId === void 0 || result.runId === fire.runId) || fire.outcome === "launched" && result.outcome !== "skipped" && result.outcome !== "buffered" && result.reservationId === void 0 && (result.runId === void 0 || result.runId === fire.runId) || unfinished && reservation && owner === activeRunId);
+  return permitted ? void 0 : new import_TriggerError.TriggerError({
+    code: "stale_owner",
+    message: `result no longer owns trigger ${result.triggerId} occurrence ${result.occurrence}`
+  });
+};
+const listed = (trigger, held = {}) => ({
+  triggerId: trigger.id,
+  trigger: Decode.succeed(trigger),
+  ...held
+});
+const historyLimit = (limit) => limit === void 0 || Number.isSafeInteger(limit) && limit > 0 ? Effect.succeed(limit) : Effect.fail(
+  new import_TriggerError.TriggerError({
+    code: "invalid_options",
+    message: `history limit must be a positive safe integer, received ${limit}`,
+    path: "limit"
+  })
+);
+const pruneCutoff = (olderThan) => Number.isSafeInteger(olderThan) ? Effect.succeed(olderThan) : Effect.fail(
+  new import_TriggerError.TriggerError({
+    code: "invalid_options",
+    message: `prune cutoff must be a safe integer, received ${olderThan}`,
+    path: "olderThan"
+  })
+);
+const compareNewestFirst = (left, right) => right.occurrence - left.occurrence || (right.triggerId < left.triggerId ? -1 : right.triggerId > left.triggerId ? 1 : 0);
+const isAfterCursor = (record, cursor) => compareNewestFirst(cursor, record) < 0;
+const historyPage = (records, limit) => {
+  if (limit === void 0 || records.length <= limit) return { items: records };
+  const items = records.slice(0, limit);
+  const last = items[items.length - 1];
+  return { items, nextCursor: { triggerId: last.triggerId, occurrence: last.occurrence } };
+};
+class TriggerStore extends Context.Service()("flows/triggers/TriggerStore") {
+}
+const unavailable = (method) => Effect.fail(new import_TriggerError.TriggerError({ code: "store", message: `${method} is unavailable` }));
+const makeNoop = (overrides = {}) => ({
+  register: () => unavailable("register"),
+  get: () => unavailable("get"),
+  list: () => unavailable("list"),
+  listEnabled: () => unavailable("listEnabled"),
+  claimFire: () => unavailable("claimFire"),
+  claimPending: () => unavailable("claimPending"),
+  recordResult: () => unavailable("recordResult"),
+  restorePending: () => unavailable("restorePending"),
+  setPending: () => unavailable("setPending"),
+  activeRun: () => unavailable("activeRun"),
+  activeOccurrence: () => unavailable("activeOccurrence"),
+  clearActive: () => unavailable("clearActive"),
+  history: () => unavailable("history"),
+  pruneFires: () => unavailable("pruneFires"),
+  inspect: () => unavailable("inspect"),
+  heartbeat: () => unavailable("heartbeat"),
+  lastHeartbeat: () => unavailable("lastHeartbeat"),
+  ...overrides
+});
+const layerNoop = (overrides = {}) => Layer.succeed(TriggerStore)(makeNoop(overrides));
+//# sourceMappingURL=TriggerStore.js.map

package/dist/cjs/TriggerStore.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/TriggerStore.ts"],
+  "sourcesContent": ["/**\n * Durable trigger declaration and fire store.\n *\n * @see packages/smithers/agent/triggers/docs/api.md\n *\n * @since 0.1.0\n */\n\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport type * as Option from \"effect/Option\"\n// `Result` already names the reported end of an occurrence in this module, so\n// the `effect/Result` a listed row decodes to is imported as `Decode`.\nimport * as Decode from \"effect/Result\"\nimport type { Action } from \"./Overlap.ts\"\nimport type { Trigger } from \"./Trigger.ts\"\nimport { TriggerError } from \"./TriggerError.ts\"\n\n/**\n * A stored trigger, with the revision that fences concurrent edits and\n * when it last fired.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Registered extends Trigger {\n  readonly revision: number\n  readonly lastFiredAt?: number | undefined\n}\n/**\n * One scheduled occurrence of a trigger, addressed by its occurrence\n * number so a retry cannot fire it twice.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Fire {\n  readonly triggerId: string\n  readonly occurrence: number\n}\n/**\n * A {@link Fire} together with the revision it was computed from and whether\n * it is resuming a buffered occurrence.\n *\n * The overlap policy is deliberately absent. A claim applies the policy stored\n * on the trigger row, read inside the same transaction, so a caller holding a\n * stale snapshot cannot fire a trigger that has since been disabled, cannot\n * point it at a different flow, and cannot supersede a run that the stored\n * declaration says to leave alone. `expectedRevision` is the fence: a claim\n * whose revision no longer matches the row is refused with `revision_mismatch`\n * so the caller re-reads before deciding again.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface ClaimFire extends Fire {\n  readonly expectedRevision: number\n  readonly resumeBuffered?: boolean | undefined\n}\n/**\n * The outcome of claiming an occurrence: either another worker holds it, or\n * this caller does and must take `action`.\n *\n * A claim that hands the caller work to launch always names the reservation it\n * wrote against the trigger row, so the caller has an id to release. A claim\n * that only records a decision has no reservation and names none: the two\n * shapes are separate so a caller cannot read a reservation id that was never\n * written.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Claim =\n  | { readonly claimed: false }\n  | { readonly claimed: true; readonly action: Extract<Action, \"skip\" | \"buffer\"> }\n  | {\n    readonly claimed: true\n    readonly action: Extract<Action, \"fire\" | \"supersede\">\n    readonly reservationId: string\n    readonly activeRunId?: string | undefined\n  }\n\n/**\n * Time after which an uncommitted launch reservation may be reclaimed.\n *\n * Both store implementations use this value so swapping the test store for\n * the SQL store cannot change recovery timing.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const reservationLeaseMs = 5 * 60 * 1000\n\n/**\n * The prefix marking an `active_run_id` that is a launch reservation rather\n * than a run the runtime knows about.\n *\n * A reservation is written by the claim and replaced by the real run id once\n * the launch reports one, so both stores and the scheduler read this prefix.\n * It is a contract between them and lives here rather than being re-spelled at\n * each site.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const reservationPrefix = \"trigger-reservation:\"\n\n/**\n * The reservation id one occurrence of one trigger claims.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const reservationId = (triggerId: string, occurrence: number, attempt?: string): string =>\n  `${reservationPrefix}${triggerId}:${attempt === undefined ? \"\" : `${attempt}:`}${occurrence}`\n\n/**\n * Whether a stored `active_run_id` is a launch reservation.\n *\n * @category predicates\n * @since 0.1.0\n */\nexport const isReservation = (runId: string | undefined): boolean =>\n  runId !== undefined && runId.startsWith(reservationPrefix)\n\n/**\n * Reads the occurrence encoded in a launch reservation.\n *\n * @category getters\n * @since 0.1.0\n */\nexport const reservationOccurrence = (runId: string): number | undefined => {\n  if (!isReservation(runId)) return undefined\n  const occurrence = Number(runId.slice(runId.lastIndexOf(\":\") + 1))\n  return Number.isFinite(occurrence) ? occurrence : undefined\n}\n\n/**\n * How a claimed occurrence ended.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Outcome = \"launched\" | \"completed\" | \"skipped\" | \"buffered\" | \"superseded\" | \"failed\"\n/**\n * The reported end of one occurrence, with the run it started when it\n * launched one.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Result =\n  & Fire\n  & { readonly error?: string | undefined }\n  & (\n    | { readonly outcome: \"launched\"; readonly runId: string; readonly reservationId: string }\n    | {\n      readonly outcome: Exclude<Outcome, \"launched\">\n      readonly runId?: string | undefined\n      readonly reservationId?: string | undefined\n    }\n  )\n\n/**\n * Refuses results that no longer own a permissible fire transition.\n * Launched run ids are validated at runtime for adapters outside TypeScript.\n *\n * @category predicates\n * @since 1.0.0-rc.0\n */\nexport const resultRefusal = (\n  result: Result,\n  fire: FireRecord | undefined,\n  activeRunId: string | undefined\n): TriggerError | undefined => {\n  if (result.outcome === \"launched\" && (typeof result.runId !== \"string\" || result.runId.trim().length === 0)) {\n    return new TriggerError({ code: \"invalid_options\", message: \"launched requires a non-empty runId\", path: \"runId\" })\n  }\n  const unfinished = fire?.outcome === null || fire?.outcome === \"buffered\"\n  const reservation = activeRunId !== undefined && isReservation(activeRunId) &&\n    reservationOccurrence(activeRunId) === result.occurrence\n  const owner = result.reservationId ?? result.runId ?? (reservation ? activeRunId : undefined)\n  const permitted = result.outcome === \"launched\"\n    ? unfinished && reservation && result.reservationId === activeRunId\n    : fire !== undefined && (\n      // A repeated decision or settlement is harmless; callers do not rewrite it.\n      (fire.outcome === result.outcome && (result.runId === undefined || result.runId === fire.runId)) ||\n      (fire.outcome === \"launched\" && result.outcome !== \"skipped\" && result.outcome !== \"buffered\" &&\n        result.reservationId === undefined && (result.runId === undefined || result.runId === fire.runId)) ||\n      (unfinished && reservation && owner === activeRunId)\n    )\n  return permitted ? undefined : new TriggerError({\n    code: \"stale_owner\",\n    message: `result no longer owns trigger ${result.triggerId} occurrence ${result.occurrence}`\n  })\n}\n\n/**\n * One row of the fire ledger: a claimed occurrence and what became of it.\n *\n * `outcome` is `null` between a claim and its `recordResult`, the window in\n * which a launch is reserved but not yet reported.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface FireRecord extends Fire {\n  readonly outcome: Outcome | null\n  readonly runId?: string | undefined\n  readonly error?: string | undefined\n}\n\n/**\n * A ledger query. Every filter narrows; `cursor` is the last record of the\n * previous page, so the page after it holds only older records; `limit` caps\n * a page and must be a positive safe integer when stated. With no limit the\n * whole ledger answers in one page.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface HistoryQuery {\n  readonly triggerId?: string | undefined\n  readonly runId?: string | undefined\n  readonly outcome?: Outcome | undefined\n  readonly cursor?: Fire | undefined\n  readonly limit?: number | undefined\n}\n\n/**\n * One page of the ledger, newest occurrence first, with the cursor that\n * addresses the next page when the limit cut the page short.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface HistoryPage {\n  readonly items: ReadonlyArray<FireRecord>\n  readonly nextCursor?: Fire | undefined\n}\n\n/**\n * What one trigger holds right now: the run or launch reservation on its row\n * and the occurrence buffered behind it. A plain read; `activeRun` is the read\n * that expires a stale reservation.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Held {\n  readonly activeRunId?: string | undefined\n  readonly pendingAt?: number | undefined\n}\n\n/**\n * One row of a listing: what the trigger holds right now, and either the\n * declaration the row decoded to or the failure it could not be read through.\n *\n * `trigger` is an `effect/Result`: narrow it with `Result.isFailure` before\n * reading the declaration. An undecodable row is isolated here rather than\n * failing the whole listing,\n * so one corrupt input cannot stop every other trigger from being scheduled.\n * The held state travels with the row because a scheduler tick would otherwise\n * ask for it again per trigger, once to expire a reservation that is not there\n * and once for a buffered occurrence that is not there either.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Listed extends Held {\n  readonly triggerId: string\n  readonly trigger: Decode.Result<Registered, TriggerError>\n}\n\n/**\n * A listed row for a declaration that decoded, holding what the trigger holds\n * right now. Both stores build their rows through this, so a caller composing\n * a store or a scheduler fixture of its own does not restate the shape.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const listed = (trigger: Registered, held: Held = {}): Listed => ({\n  triggerId: trigger.id,\n  trigger: Decode.succeed(trigger),\n  ...held\n})\n\n/**\n * The last poll one scheduler host recorded.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Heartbeat {\n  readonly host: string\n  readonly tickedAt: number\n}\n\n/**\n * Validates a {@link HistoryQuery} limit: absent, or a positive safe integer.\n * Both stores apply this before reading so swapping one for the other cannot\n * change which queries are refused.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const historyLimit = (limit: number | undefined): Effect.Effect<number | undefined, TriggerError> =>\n  limit === undefined || (Number.isSafeInteger(limit) && limit > 0)\n    ? Effect.succeed(limit)\n    : Effect.fail(\n      new TriggerError({\n        code: \"invalid_options\",\n        message: `history limit must be a positive safe integer, received ${limit}`,\n        path: \"limit\"\n      })\n    )\n\n/**\n * Validates a prune cutoff: any safe integer. Both stores apply this before\n * deleting so swapping one for the other cannot change which cutoffs are\n * refused.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const pruneCutoff = (olderThan: number): Effect.Effect<number, TriggerError> =>\n  Number.isSafeInteger(olderThan)\n    ? Effect.succeed(olderThan)\n    : Effect.fail(\n      new TriggerError({\n        code: \"invalid_options\",\n        message: `prune cutoff must be a safe integer, received ${olderThan}`,\n        path: \"olderThan\"\n      })\n    )\n\n/**\n * Newest occurrence first; equal occurrences of different triggers order by\n * descending trigger id so a cursor names one position.\n *\n * @category ordering\n * @since 1.0.0-rc.0\n */\nexport const compareNewestFirst = (left: Fire, right: Fire): number =>\n  right.occurrence - left.occurrence ||\n  (right.triggerId < left.triggerId ? -1 : right.triggerId > left.triggerId ? 1 : 0)\n\n/**\n * Whether a record lies after `cursor` in {@link compareNewestFirst} order.\n *\n * @category predicates\n * @since 1.0.0-rc.0\n */\nexport const isAfterCursor = (record: Fire, cursor: Fire): boolean => compareNewestFirst(cursor, record) < 0\n\n/**\n * Cuts an ordered, filtered record list to one page. The caller fetches one\n * record past the limit; that record's presence is what says a next page\n * exists, and the page's last record is the cursor addressing it.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const historyPage = (records: ReadonlyArray<FireRecord>, limit: number | undefined): HistoryPage => {\n  if (limit === undefined || records.length <= limit) return { items: records }\n  const items = records.slice(0, limit)\n  const last = items[items.length - 1] as FireRecord\n  return { items, nextCursor: { triggerId: last.triggerId, occurrence: last.occurrence } }\n}\n\n/**\n * Durable trigger state: registration, listing, and the claim protocol that\n * keeps two schedulers from firing the same occurrence.\n *\n * Neither listing is a due-time query. Due-ness is a cron computation the\n * scheduler performs against its own watermark, so the store is asked only for\n * the rows eligible to be considered. A scheduler tick reads `list`, not\n * `listEnabled`: a disabled trigger can still hold an active occurrence that\n * has to recover, and the tick skips only its new claims. `listEnabled`\n * answers the narrower question for a caller that wants the declarations.\n *\n * A claim, result, pending-state, or active-run method fails with\n * `unknown_trigger` when the row it addresses does not exist. `get` answers\n * `None` for an absent row and `register` creates one. `clearActive` is a\n * compare-and-swap that cannot tell a missing trigger from a run id that no\n * longer matches, so it stays a no-op for both. `history`, `pruneFires`,\n * `heartbeat`, and `lastHeartbeat` address the whole store.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service {\n  readonly register: (trigger: Trigger) => Effect.Effect<Registered, TriggerError>\n  readonly get: (triggerId: string) => Effect.Effect<Option.Option<Registered>, TriggerError>\n  /**\n   * Every trigger, enabled or not, ordered by id. This is what a scheduler\n   * tick polls: see {@link Listed} for why a row carries its decode result and\n   * its held state rather than a bare declaration.\n   */\n  readonly list: () => Effect.Effect<ReadonlyArray<Listed>, TriggerError>\n  readonly listEnabled: () => Effect.Effect<ReadonlyArray<Registered>, TriggerError>\n  readonly claimFire: (fire: ClaimFire) => Effect.Effect<Claim, TriggerError>\n  /**\n   * Claims the buffered occurrence, when one exists.\n   *\n   * One transaction reads the occurrence, applies the same claim protocol as\n   * {@link Service.claimFire}, and clears the buffer only when the decision\n   * consumes it. A concurrent buffer decision keeps it pending. No failure can\n   * land between reading the buffer and claiming it.\n   */\n  readonly claimPending: (fire: {\n    readonly triggerId: string\n    readonly expectedRevision: number\n  }) => Effect.Effect<\n    Option.Option<{ readonly occurrence: number; readonly claim: Claim }>,\n    TriggerError\n  >\n  readonly recordResult: (result: Result) => Effect.Effect<void, TriggerError>\n  /** Atomically re-arms unfinished work and releases only its matching reservation.\n   * A retained predecessor is restored with the pending pointer in the same write.\n   * A stale token fails with `stale_owner`; a failed write leaves the lease intact.\n   */\n  readonly restorePending: (fire: Fire & { readonly reservationId: string }) => Effect.Effect<void, TriggerError>\n  readonly setPending: (fire: Fire) => Effect.Effect<void, TriggerError>\n  readonly activeRun: (triggerId: string) => Effect.Effect<Option.Option<string>, TriggerError>\n  /**\n   * Returns the occurrence owned by one active run or launch reservation.\n   *\n   * `lastFiredAt` cannot answer this: later skipped and buffered occurrences\n   * advance that cursor while an older run remains active.\n   */\n  readonly activeOccurrence: (\n    triggerId: string,\n    runId: string\n  ) => Effect.Effect<Option.Option<number>, TriggerError>\n  readonly clearActive: (triggerId: string, runId: string) => Effect.Effect<void, TriggerError>\n  /**\n   * Reads the fire ledger newest first. See {@link HistoryQuery} for the\n   * filters and paging contract; a limit that is not a positive safe integer\n   * is refused with `invalid_options`.\n   */\n  readonly history: (query?: HistoryQuery) => Effect.Effect<HistoryPage, TriggerError>\n  /**\n   * Deletes settled fire ledger rows older than `olderThan`, answering how\n   * many it removed. Nothing else in the store deletes from the ledger, so a\n   * host that never calls this keeps one row per occurrence forever.\n   *\n   * A row is settled when its outcome is `completed`, `failed`, `skipped`, or\n   * `superseded`. The occurrence a trigger currently buffers and the row\n   * naming its active run are kept whatever their age, so pruning cannot take\n   * state the scheduler still reads. `olderThan` that is not a safe integer is\n   * refused with `invalid_options`.\n   */\n  readonly pruneFires: (options: { readonly olderThan: number }) => Effect.Effect<number, TriggerError>\n  /**\n   * Reads what one trigger holds without expiring anything, so a listing can\n   * report a reservation or a buffered occurrence exactly as the row has it.\n   */\n  readonly inspect: (triggerId: string) => Effect.Effect<Held, TriggerError>\n  /** Records that `host` polled the store at the store clock's current time. */\n  readonly heartbeat: (host: string) => Effect.Effect<void, TriggerError>\n  /** The most recent heartbeat across every host, or `None` when no scheduler has ever polled. */\n  readonly lastHeartbeat: () => Effect.Effect<Option.Option<Heartbeat>, TriggerError>\n}\n\n/**\n * The {@link Service} tag.\n *\n * @category services\n * @since 0.1.0\n */\nexport class TriggerStore extends Context.Service<TriggerStore, Service>()(\"flows/triggers/TriggerStore\") {}\n\nconst unavailable = (method: string): Effect.Effect<never, TriggerError> =>\n  Effect.fail(new TriggerError({ code: \"store\", message: `${method} is unavailable` }))\n\n/**\n * A {@link Service} that fails every method as unavailable, for an\n * environment with no trigger store. Overrides replace individual methods.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeNoop = (overrides: Partial<Service> = {}): Service => ({\n  register: () => unavailable(\"register\"),\n  get: () => unavailable(\"get\"),\n  list: () => unavailable(\"list\"),\n  listEnabled: () => unavailable(\"listEnabled\"),\n  claimFire: () => unavailable(\"claimFire\"),\n  claimPending: () => unavailable(\"claimPending\"),\n  recordResult: () => unavailable(\"recordResult\"),\n  restorePending: () => unavailable(\"restorePending\"),\n  setPending: () => unavailable(\"setPending\"),\n  activeRun: () => unavailable(\"activeRun\"),\n  activeOccurrence: () => unavailable(\"activeOccurrence\"),\n  clearActive: () => unavailable(\"clearActive\"),\n  history: () => unavailable(\"history\"),\n  pruneFires: () => unavailable(\"pruneFires\"),\n  inspect: () => unavailable(\"inspect\"),\n  heartbeat: () => unavailable(\"heartbeat\"),\n  lastHeartbeat: () => unavailable(\"lastHeartbeat\"),\n  ...overrides\n})\n\n/**\n * Provides {@link makeNoop}.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerNoop = (overrides: Partial<Service> = {}): Layer.Layer<TriggerStore> =>\n  Layer.succeed(TriggerStore)(makeNoop(overrides))\n"],
+  "mappings": "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",
+  "names": []
+}