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

package/src/ClaimDecision.ts

@@ -0,0 +1,303 @@
+/**
+ * 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 * as Overlap from "./Overlap.ts"
+import type { Overlap as Policy } from "./Trigger.ts"
+import { TriggerError } from "./TriggerError.ts"
+import {
+  type Claim,
+  type ClaimFire,
+  isReservation,
+  type Outcome,
+  reservationLeaseMs,
+  reservationOccurrence
+} 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" }>
+
+const decided = (claim: Claim, writes: ReadonlyArray<Write>): AdmittedDecision => ({ _tag: "Decided", claim, writes })
+
+/**
+ * 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 const lease = (input: {
+  readonly activeRunId?: string | undefined
+  readonly activeClaimedAt?: number | undefined
+  readonly pending?: number | undefined
+  readonly now: number
+  readonly unfinished?: Fire | undefined
+}): Lease => {
+  const { activeClaimedAt, activeRunId, now, pending, unfinished } = input
+  if (activeRunId === undefined) return { _tag: "Idle" }
+  if (!isReservation(activeRunId) || (activeClaimedAt !== undefined && activeClaimedAt > now - reservationLeaseMs)) {
+    return { _tag: "Held", runId: activeRunId }
+  }
+  const occurrence = reservationOccurrence(activeRunId)
+  if (occurrence === undefined || unfinished === undefined) return { _tag: "Expired", expected: activeRunId }
+  const predecessor = unfinished.runId
+  return {
+    _tag: "Expired",
+    expected: activeRunId,
+    pending: Overlap.pendingAfter({ running: false, pending, due: occurrence }),
+    ...(predecessor !== undefined && !isReservation(predecessor) ? { recovered: predecessor } : {})
+  }
+}
+
+/**
+ * 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 const refuse = (
+  snapshot: Pick<Snapshot, "enabled" | "revision">,
+  fire: ClaimFire
+): TriggerError | undefined => {
+  if (snapshot.revision !== fire.expectedRevision) {
+    return new TriggerError({
+      code: "revision_mismatch",
+      message: `trigger ${fire.triggerId} is at revision ${snapshot.revision}, not the claimed ${fire.expectedRevision}`
+    })
+  }
+  if (!snapshot.enabled) {
+    return new TriggerError({ code: "trigger_disabled", message: `trigger ${fire.triggerId} is disabled` })
+  }
+  return undefined
+}
+
+/**
+ * Applies the claim protocol to a snapshot.
+ *
+ * @category decision
+ * @since 1.0.0-rc.0
+ */
+export const decide = (input: Input): Decision => {
+  const refusal = refuse(input.snapshot, input.fire)
+  return refusal === undefined ? decideFenced(input) : { _tag: "Refused", error: refusal }
+}
+
+/**
+ * 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 const decideFenced = ({ claimedAt, fire, reservationId, snapshot }: Input): AdmittedDecision => {
+  let activeRunId = snapshot.activeRunId
+  let pending = snapshot.pending
+  // A reservation with no claim timestamp predates the lease column. Nothing
+  // writes that shape now, so treating it as expired is the only way such a
+  // row is ever reclaimed.
+  const expiredReservation = activeRunId !== undefined && isReservation(activeRunId) &&
+      (snapshot.activeClaimedAt === undefined || snapshot.activeClaimedAt <= claimedAt - reservationLeaseMs)
+    ? activeRunId
+    : undefined
+  const existing = snapshot.existingFire
+  if (existing !== undefined) {
+    const resumableBuffer = fire.resumeBuffered === true && existing.outcome === "buffered"
+    const resumableReservation = existing.outcome === null &&
+      (activeRunId === undefined ||
+        (reservationOccurrence(activeRunId) === fire.occurrence && expiredReservation !== undefined))
+    const resumableSupersede = fire.resumeBuffered === true && existing.outcome === null &&
+      snapshot.overlap === "supersede" && activeRunId !== undefined && existing.runId === activeRunId
+    if (!resumableBuffer && !resumableReservation && !resumableSupersede) return decided({ claimed: false }, [])
+  }
+  const writes: Array<Write> = []
+  if (expiredReservation !== undefined) {
+    const expiredOccurrence = reservationOccurrence(expiredReservation)
+    const expiredFire = expiredOccurrence === undefined ? undefined : snapshot.activeFire
+    if (
+      expiredOccurrence !== undefined && expiredFire !== undefined &&
+      (expiredFire.outcome === null || expiredFire.outcome === "buffered")
+    ) {
+      if (snapshot.overlap === "supersede") {
+        const predecessor = expiredFire.runId
+        activeRunId = predecessor !== undefined && !isReservation(predecessor) ? predecessor : undefined
+        if (expiredOccurrence !== fire.occurrence) {
+          writes.push({ _tag: "SetOutcome", occurrence: expiredOccurrence, outcome: "superseded", whileOpen: false })
+        }
+      } else {
+        activeRunId = undefined
+        if (expiredOccurrence !== fire.occurrence) {
+          pending = Overlap.pendingAfter({ running: false, pending, due: expiredOccurrence })
+        }
+      }
+    } else {
+      activeRunId = undefined
+    }
+    writes.push({ _tag: "ReleaseReservation", expected: expiredReservation, activeRunId, pending })
+  }
+  const state: Overlap.State = { running: activeRunId !== undefined, pending, due: fire.occurrence }
+  const action = Overlap.decide(snapshot.overlap, state)
+  // A skip or buffer is complete inside the claim transaction. A fire or
+  // supersede is only reserved here; its cursor advances when `recordResult`
+  // makes the launched run durable.
+  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 !== undefined) {
+    if (isReservation(activeRunId)) {
+      const activeOccurrence = reservationOccurrence(activeRunId)
+      if (activeOccurrence !== undefined) {
+        const predecessor = snapshot.activeFire?.runId
+        if (predecessor !== undefined && !isReservation(predecessor)) supersededRunId = predecessor
+        writes.push({ _tag: "SetOutcome", occurrence: activeOccurrence, outcome: "superseded", whileOpen: true })
+      }
+    }
+    if (supersededRunId !== undefined && !isReservation(supersededRunId)) {
+      writes.push({ _tag: "SetRunId", occurrence: fire.occurrence, runId: supersededRunId })
+    }
+  }
+  writes.push({ _tag: "Reserve", reservationId, claimedAt })
+  return decided(
+    {
+      claimed: true,
+      action,
+      reservationId,
+      ...(supersededRunId === undefined ? {} : { activeRunId: supersededRunId })
+    },
+    writes
+  )
+}

package/src/Cron.ts

@@ -0,0 +1,173 @@
+/**
+ * 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 Clock from "effect/Clock"
+import * as EffectCron from "effect/Cron"
+import * as Effect from "effect/Effect"
+import * as Result from "effect/Result"
+import * as WallClock from "./internal/WallClock.ts"
+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
+}
+
+const exhausted = (cron: Cron, search: string, cause: unknown): TriggerError =>
+  new TriggerError({
+    code: "unsatisfiable_cron",
+    message: `cron expression '${cron.expression}' has no ${search} occurrence`,
+    cause
+  })
+
+const attempt = <A>(cron: Cron, search: string, find: () => A): Effect.Effect<A, TriggerError> =>
+  Effect.try({ try: find, catch: (cause) => exhausted(cron, search, cause) })
+
+/**
+ * The first occurrence strictly after `from`.
+ *
+ * @category getters
+ * @since 0.1.0
+ */
+export const next = (cron: Cron, from: Date): Effect.Effect<Date, TriggerError> =>
+  attempt(cron, "next", () => new Date(WallClock.next(WallClock.compile(cron.value), from.getTime())))
+
+/**
+ * Returns the latest occurrence at or before `at`.
+ *
+ * @category getters
+ * @since 0.1.0
+ */
+export const previousAtOrBefore = (cron: Cron, at: Date): Effect.Effect<Date, TriggerError> =>
+  attempt(
+    cron,
+    "previous",
+    () => new Date(WallClock.previousAtOrBefore(WallClock.compile(cron.value), at.getTime()))
+  )
+
+/**
+ * The greatest number of occurrences one search returns when its caller states
+ * no limit of its own.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export 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 const occurrencesBetween = (
+  cron: Cron,
+  from: Date,
+  to: Date,
+  limit?: number | undefined
+): Effect.Effect<ReadonlyArray<Date>, TriggerError> => {
+  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0)) {
+    return Effect.fail(
+      new 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: Array<Date> = []
+    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 !== undefined) return search
+  return search.pipe(
+    Effect.flatMap((occurrences) =>
+      occurrences.length > maxOccurrences
+        ? Effect.fail(
+          new TriggerError({
+            code: "catch_up_bound_exceeded",
+            message: `interval contains more than ${maxOccurrences} occurrences; maxOccurrences is ${maxOccurrences}`
+          })
+        )
+        : Effect.succeed(occurrences)
+    )
+  )
+}
+
+/**
+ * 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 const parse = (expression: string, timezone?: string): Effect.Effect<Cron, TriggerError> =>
+  Effect.gen(function*() {
+    const parsed = EffectCron.parse(expression, timezone)
+    if (Result.isFailure(parsed)) {
+      return yield* Effect.fail(
+        new TriggerError({ code: "invalid_cron", message: parsed.failure.message, cause: parsed.failure })
+      )
+    }
+    const cron: Cron = {
+      expression,
+      ...(timezone === undefined ? {} : { timezone }),
+      value: parsed.success
+    }
+    const now = yield* Clock.currentTimeMillis
+    yield* next(cron, new Date(now))
+    return cron
+  })

package/src/DispatchReader.ts

@@ -0,0 +1,179 @@
+/**
+ * The `@smthrs/control` `DispatchReader` port served from a `TriggerStore`.
+ *
+ * `Control.list` answers `{ _tag: "triggers" }` and `{ _tag: "fires" }` through
+ * the port declared in `@smthrs/control/DispatchReader`. The port lives there
+ * because this package depends on control (the scheduler launches runs through
+ * it); the adapter lives here because only this package can read the store.
+ * The host composes the two: {@link layer} over the same store the scheduler
+ * writes.
+ *
+ * @see packages/smithers/agent/triggers/docs/api.md
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import type { ControlError } from "@smthrs/control/ControlError"
+import { PersistenceError } from "@smthrs/control/ControlError"
+import { defaultPageSize, type FireSummary, type TriggerSummary } from "@smthrs/control/ControlSchema"
+import * as Port from "@smthrs/control/DispatchReader"
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import * as Result from "effect/Result"
+import * as Cron from "./Cron.ts"
+import type { TriggerError } from "./TriggerError.ts"
+import { type FireRecord, type Held, isReservation, type Registered, TriggerStore } from "./TriggerStore.ts"
+
+/**
+ * How many upcoming occurrences a trigger summary carries.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const nextOccurrenceCount = 5
+
+/**
+ * How many ledger rows one `fires` page needs: every row before the page's
+ * offset cursor, the page, and one more so `Control.list` can tell a next page
+ * exists. A cursor Control will refuse reads nothing extra: it answers
+ * `undefined`, and the refusal comes from Control.
+ */
+const firesNeeded = (request: Port.FiresRequest): number | undefined => {
+  const start = request.cursor === undefined ? 0 : Number(request.cursor)
+  const size = request.limit ?? defaultPageSize
+  return Number.isSafeInteger(start) && start >= 0 && Number.isSafeInteger(size) && size >= 1
+    ? start + size + 1
+    : undefined
+}
+
+const persistence = (operation: string) => (error: TriggerError): ControlError =>
+  new PersistenceError({ operation, message: error.message, cause: error })
+
+/**
+ * The next {@link nextOccurrenceCount} occurrences strictly after `now`, as
+ * epoch milliseconds in ascending order.
+ *
+ * @category getters
+ * @since 1.0.0-rc.0
+ */
+export const nextOccurrences = (
+  trigger: Pick<Registered, "cron" | "timezone">,
+  now: number
+): Effect.Effect<ReadonlyArray<number>, TriggerError> =>
+  Effect.gen(function*() {
+    const cron = yield* Cron.parse(trigger.cron, trigger.timezone)
+    const occurrences: Array<number> = []
+    let from = new Date(now)
+    while (occurrences.length < nextOccurrenceCount) {
+      from = yield* Cron.next(cron, from)
+      occurrences.push(from.getTime())
+    }
+    return occurrences
+  })
+
+/**
+ * Maps one stored trigger and what it holds to the control plane's summary.
+ *
+ * A launch reservation is not a run the runtime knows about, so it is
+ * reported as no active run; the ledger still shows the claimed occurrence.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const toTriggerSummary = (
+  trigger: Registered,
+  held: Held,
+  nextOccurrencesMs: ReadonlyArray<number>,
+  schedulerLastTickMs: Option.Option<number>
+): TriggerSummary => ({
+  triggerId: trigger.id,
+  flowId: trigger.flowId,
+  input: trigger.input,
+  cron: trigger.cron,
+  ...(trigger.timezone === undefined ? {} : { timezone: trigger.timezone }),
+  overlap: trigger.overlap,
+  catchUp: trigger.catchUp,
+  maxCatchUp: trigger.maxCatchUp,
+  enabled: trigger.enabled,
+  revision: trigger.revision,
+  ...(trigger.lastFiredAt === undefined ? {} : { lastFiredAtMs: trigger.lastFiredAt }),
+  ...(held.pendingAt === undefined ? {} : { pendingAtMs: held.pendingAt }),
+  ...(held.activeRunId === undefined || isReservation(held.activeRunId) ? {} : { activeRunId: held.activeRunId }),
+  nextOccurrencesMs,
+  ...(Option.isSome(schedulerLastTickMs) ? { schedulerLastTickMs: schedulerLastTickMs.value } : {})
+})
+
+/**
+ * Maps one ledger row to the control plane's fire summary.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const toFireSummary = (record: FireRecord): FireSummary => ({
+  triggerId: record.triggerId,
+  occurrenceAtMs: record.occurrence,
+  outcome: record.outcome,
+  ...(record.runId === undefined ? {} : { runId: record.runId }),
+  ...(record.error === undefined ? {} : { error: record.error })
+})
+
+/**
+ * Builds the port over the ambient {@link TriggerStore}.
+ *
+ * `list` answers every trigger the store holds, taking each row's held state
+ * from the listing itself; `fires` pushes the request's filters into the
+ * ledger query and answers the matching rows newest first, reading only as
+ * many as the requested page needs.
+ * `Control.list` applies the filters again and pages. A store failure is a
+ * `PersistenceError` naming the listing that failed.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const make: Effect.Effect<Port.Service, never, TriggerStore> = Effect.gen(function*() {
+  const store = yield* TriggerStore
+  return Port.make({
+    list: Effect.fn("DispatchReader.list")(() =>
+      Effect.gen(function*() {
+        const now = yield* Clock.currentTimeMillis
+        const heartbeat = yield* store.lastHeartbeat()
+        const lastTick = Option.map(heartbeat, (beat) => beat.tickedAt)
+        const listing = yield* store.list()
+        return yield* Effect.forEach(listing, (row) =>
+          Effect.gen(function*() {
+            // A row the store could not decode fails the listing rather than
+            // being reported as a trigger with invented fields; the failure
+            // names the row. The listing already carries what `inspect` reads,
+            // so a summary costs no second read per trigger.
+            if (Result.isFailure(row.trigger)) return yield* Effect.fail(row.trigger.failure)
+            const trigger = row.trigger.success
+            const upcoming = yield* nextOccurrences(trigger, now)
+            return toTriggerSummary(trigger, row, upcoming, lastTick)
+          }))
+      }).pipe(Effect.mapError(persistence("triggers")))
+    ),
+    fires: Effect.fn("DispatchReader.fires")((request) =>
+      store.history({
+        triggerId: request.filters?.triggerId,
+        runId: request.filters?.runId,
+        outcome: request.filters?.outcome,
+        limit: firesNeeded(request)
+      }).pipe(
+        Effect.map((page) => page.items.map(toFireSummary)),
+        Effect.mapError(persistence("fires"))
+      )
+    )
+  })
+})
+
+/**
+ * Provides the control plane's `DispatchReader` from the ambient
+ * {@link TriggerStore}, so `Control.list` answers `triggers` and `fires` from
+ * the store the scheduler writes.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layer: Layer.Layer<Port.DispatchReader, never, TriggerStore> = Layer.effect(Port.DispatchReader)(make)