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

package/docs/guides/testing.md

@@ -0,0 +1,157 @@
+---
+title: "Test trigger code"
+description: "Test schedules and triggers deterministically: the in-memory store, the recording runner, a test clock instead of wall time, and the noop store that proves a composition reaches nothing."
+sidebar:
+  order: 5
+---
+
+Nothing in this package reads wall time or reaches a network directly. Time is
+the Effect `Clock`, launching is the `Runner` port, and persistence is the
+`TriggerStore` contract. A test replaces those three and runs the production
+logic.
+
+## Swap the store for the in-memory one
+
+`TestTriggers.layer` is a `TriggerStore` with real claim and overlap semantics
+and no database:
+
+```ts
+import * as TestTriggers from "@smthrs/triggers/test/TestTriggers"
+import * as Layer from "effect/Layer"
+
+const store = TestTriggers.layer
+```
+
+It is not a kinder set of rules. Both stores apply one shared claim decision, so
+they return the same refusal codes in the same order, hold the same 5-minute
+reservation lease from `TriggerStore.reservationLeaseMs`, reclaim an expired
+reservation the same way, and follow the same watermark rules. Registration
+validates the declaration and serializes its input at the call boundary in both,
+`list` and `listEnabled` order by id in both, and every reading is an
+independent value that cannot be mutated back into stored state.
+
+Two things it cannot stand in for. It holds one process's state behind a `Ref`,
+so it never reports a `store` failure from a write and never shows contention
+between connections. It applies no migrations and keeps no rows, so a test about
+a schema or a column shape has nothing to read.
+
+Use `SqlTriggerStore.layer` over an in-memory SQLite database when the thing
+under test is a SQL behavior, such as migration application or a row shape.
+
+## Record launches instead of performing them
+
+`Scheduler.layerNoopRunner` answers `inspect` with `"completed"` and `cancel`
+with nothing, so launched work settles immediately. Override only what the test
+needs to observe:
+
+```ts
+import * as Scheduler from "@smthrs/triggers/Scheduler"
+import * as Effect from "effect/Effect"
+
+const launched: Array<Scheduler.StartInput> = []
+
+const runner = Scheduler.layerNoopRunner({
+  start: (input) =>
+    Effect.sync(() => {
+      launched.push(input)
+      return input.idempotencyKey
+    })
+})
+```
+
+Assert on `idempotencyKey`. It is `<triggerId>:<occurrence ISO instant>`, so it
+pins which boundary fired, not merely that something fired.
+
+To exercise a run that stays alive, keep a set of active run ids and answer
+`inspect` from it: `"active"` while the id is in the set, and the state you
+want recorded once it leaves. To exercise supersede, record what `cancel` was
+called with.
+
+## Move the clock instead of waiting
+
+```ts
+import * as Scheduler from "@smthrs/triggers/Scheduler"
+import * as Effect from "effect/Effect"
+import { TestClock } from "effect/testing"
+
+const program = Effect.scoped(Effect.gen(function*() {
+  const scheduler = yield* Scheduler.make()
+  yield* TestClock.setTime(Date.parse("2026-03-01T03:00:00.000Z"))
+  yield* scheduler.runOnce
+  yield* TestClock.setTime(Date.parse("2026-03-02T03:00:00.000Z"))
+  yield* scheduler.runOnce
+  yield* Effect.yieldNow
+}))
+```
+
+Build the scheduler with `Scheduler.make` rather than `Scheduler.layer`, so no
+supervisor fiber competes with the test for ticks, and the test decides when
+each tick happens.
+
+Two habits keep such a test honest:
+
+- Yield after a tick that launches. The launch monitor runs in a forked fiber,
+  so the terminal result is recorded after `runOnce` returns.
+- Remember that the first tick a process performs on a trigger establishes a
+  watermark and fires nothing. A test that expects a launch needs a second tick,
+  or a trigger seeded with a `lastFiredAt` through a recorded result.
+
+## Observe what the store recorded
+
+Wrap the store layer to capture `recordResult` calls, which is where every
+scheduler decision lands:
+
+```ts
+import * as TriggerStore from "@smthrs/triggers/TriggerStore"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+
+const recording = (results: Array<TriggerStore.Result>) =>
+  Layer.effect(
+    TriggerStore.TriggerStore,
+    Effect.gen(function*() {
+      const store = yield* TriggerStore.TriggerStore
+      return TriggerStore.TriggerStore.of({
+        ...store,
+        recordResult: (result) =>
+          Effect.sync(() => {
+            results.push(result)
+          }).pipe(Effect.andThen(store.recordResult(result)))
+      })
+    })
+  ).pipe(Layer.provide(TestTriggers.layer))
+```
+
+The outcomes tell the policies apart: `skipped`, `buffered`, and `superseded`
+are the three overlap decisions, and `launched` followed by `completed` is a run
+that went all the way.
+
+## Prove a composition reaches nothing
+
+`TriggerStore.layerNoop` fails every method with `store` and a message naming
+the method. Use it when a composition needs the service in its type but must
+never touch it, and override the one method a test expects to be reached. A
+scheduler tick polls `list`, so that is the override a tick needs:
+
+```ts
+import * as TriggerStore from "@smthrs/triggers/TriggerStore"
+import * as Effect from "effect/Effect"
+
+const absent = TriggerStore.layerNoop({ list: () => Effect.succeed([]) })
+```
+
+`Scheduler.layerNoop` is the matching inert scheduler, and
+`Scheduler.makeNoopRunner` the matching inert launcher.
+
+## Test the pure parts directly
+
+`Overlap.decide`, `Overlap.pendingAfter`, and `CatchUp.occurrences` are pure
+functions over explicit state. A policy question is answerable without a store,
+a clock, or a scheduler at all, and that is the cheapest place to pin a policy
+expectation:
+
+```ts
+import * as Overlap from "@smthrs/triggers/Overlap"
+
+Overlap.decide("supersede", { running: true, due: 7_200_000 }) // "supersede"
+```

package/docs/installation.md

@@ -0,0 +1,81 @@
+---
+title: "Installation"
+description: "How to get @smthrs/triggers, what it requires at runtime, the import forms it publishes, and the packages a running host adds on top."
+sidebar:
+  order: 1
+---
+
+## Get the package
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+The installed manifest resolves to the synchronized RC:
+
+```json
+{
+  "dependencies": {
+    "@smthrs/triggers": "1.0.0-rc.1"
+  }
+}
+```
+
+## Requirements
+
+- Node.js 26.4.0 or later.
+- [`effect`](https://effect.website) 4.0.0-rc.115, which supplies the `Effect`,
+  `Schema`, `Clock`, and SQL client types this package's signatures use.
+- [`@smthrs/control`](/api/control), the authoritative launch boundary. The
+  scheduler's Control-backed runner and every channel dispatch go through it.
+- [`@smthrs/database`](/api/database), for the SQL client and the durable
+  writer that `SqlTriggerStore` writes through.
+
+All three are ordinary dependencies of the package and install with it.
+
+## Import forms
+
+The root entry point re-exports every module as a namespace:
+
+```ts
+import { Cron, DispatchReader, Scheduler, SqlTriggerStore, Trigger, TriggerStore, Webhook } from "@smthrs/triggers"
+```
+
+Each module is also importable from its own subpath, which is the form these
+docs use:
+
+```ts
+import * as Scheduler from "@smthrs/triggers/Scheduler"
+import * as TriggerStore from "@smthrs/triggers/TriggerStore"
+```
+
+The in-memory store for tests lives at its own subpath:
+
+```ts
+import * as TestTriggers from "@smthrs/triggers/test/TestTriggers"
+```
+
+Three subpath forms are not public and are blocked in the package's export map:
+`@smthrs/triggers/migrations/*`, `@smthrs/triggers/internal/*`, and
+`@smthrs/triggers/*/index`. `@smthrs/triggers/package.json` is exported.
+
+Migrations are internal on purpose. `SqlTriggerStore.layer` applies
+`0001_triggers` and then `0002_reservation_lease` when it builds, so a host
+never runs them itself.
+
+## What a running host adds
+
+The package declares triggers and channels; it does not open a database or
+reach a control plane. A host that actually fires triggers composes three more
+layers:
+
+- A SQL client and a durable writer, from
+  [`@smthrs/database`](/api/database). `NodeDatabase.layer({ filename })` plus
+  `DurableWriter.layer()` is the Node pairing.
+- `SqlTriggerStore.layer`, which turns those two into a `TriggerStore`.
+- A `Scheduler.Runner`. `Scheduler.layerControlRunner` is the production one
+  and requires `Control.Control` from [`@smthrs/control`](/api/control).
+
+The composition is in [Run the scheduler in a host](./guides/run-the-scheduler.md).
+
+## Next step
+
+Register a trigger and watch it launch in the [Quickstart](./quickstart.md).

package/docs/quickstart.md

@@ -0,0 +1,163 @@
+---
+title: "Quickstart"
+description: "Register a durable trigger and watch the scheduler launch it: a SQLite store, a recording runner, and a test clock that crosses two schedule boundaries in milliseconds."
+sidebar:
+  order: 2
+---
+
+This quickstart takes one trigger from a declaration to a launched run. The
+store is the production SQLite one and the scheduler is the production one;
+only two things are substituted, and both are seams the package already has:
+the `Runner` records launches instead of reaching a control plane, and the
+Effect `Clock` is a test clock, so a nightly schedule crosses two boundaries in
+milliseconds instead of two days.
+
+By the end you will have a trigger row that remembers when it last fired, and
+one launch carrying an idempotency key derived from the occurrence.
+
+## Prerequisites
+
+- Node.js 26.4.0 or later.
+- A TypeScript project that depends on `@smthrs/triggers` and
+  `@smthrs/database`. See [Installation](./installation.md).
+
+## Compose the store, the runner, and the clock
+
+Create `quickstart.ts`. `SqlTriggerStore.layer` needs a SQL client and a
+durable writer, and it runs its own migrations when it builds:
+
+```ts
+import * as DurableWriter from "@smthrs/database/DurableWriter"
+import * as NodeDatabase from "@smthrs/database/node/NodeDatabase"
+import * as Scheduler from "@smthrs/triggers/Scheduler"
+import * as SqlTriggerStore from "@smthrs/triggers/SqlTriggerStore"
+import * as TriggerStore from "@smthrs/triggers/TriggerStore"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import { TestClock } from "effect/testing"
+
+const launched: Array<Scheduler.StartInput> = []
+
+const database = Layer.provideMerge(
+  DurableWriter.layer(),
+  NodeDatabase.layer({ filename: ":memory:" })
+)
+
+/** The launcher seam: record the launch and answer with a run id. */
+const runner = Scheduler.layerNoopRunner({
+  start: (input) =>
+    Effect.sync(() => {
+      launched.push(input)
+      return input.idempotencyKey
+    })
+})
+
+const layer = Layer.mergeAll(
+  SqlTriggerStore.layer.pipe(Layer.provide(database)),
+  runner,
+  TestClock.layer()
+)
+```
+
+`Scheduler.layerNoopRunner` answers `inspect` with `"completed"` and `cancel`
+with nothing, so a launch settles the moment it starts. The override replaces only
+`start`.
+
+## Register the trigger and run two ticks
+
+`Scheduler.make` builds a scheduler with no supervisor fiber, so the program
+decides when a tick happens. That is what makes the walkthrough deterministic:
+
+```ts
+const program = Effect.scoped(Effect.gen(function*() {
+  const triggers = yield* TriggerStore.TriggerStore
+  yield* triggers.register({
+    id: "nightly-report",
+    flowId: "reports/nightly",
+    input: { channel: "#ops" },
+    cron: "0 3 * * *",
+    timezone: "UTC",
+    overlap: "skip",
+    catchUp: "one",
+    maxCatchUp: 1,
+    enabled: true
+  })
+
+  const scheduler = yield* Scheduler.make()
+
+  // First sight of this trigger: the tick records where the clock is and
+  // fires nothing, because a trigger that has never fired owes no history.
+  yield* TestClock.setTime(Date.parse("2026-03-01T03:00:00.000Z"))
+  yield* scheduler.runOnce
+
+  // A boundary has passed since that watermark, so this tick launches it.
+  yield* TestClock.setTime(Date.parse("2026-03-02T03:00:00.000Z"))
+  yield* scheduler.runOnce
+  yield* Effect.yieldNow
+
+  return yield* triggers.get("nightly-report")
+}))
+
+const registered = await Effect.runPromise(program.pipe(Effect.provide(layer)))
+console.log(launched)
+console.log(registered)
+```
+
+Run the file with your TypeScript runner. The recorded launch and the stored
+row look like this:
+
+```text
+[
+  {
+    flowId: 'reports/nightly',
+    input: { channel: '#ops' },
+    idempotencyKey: 'nightly-report:2026-03-02T03:00:00.000Z'
+  }
+]
+{
+  _id: 'Option',
+  _tag: 'Some',
+  value: {
+    id: 'nightly-report',
+    flowId: 'reports/nightly',
+    input: { channel: '#ops' },
+    cron: '0 3 * * *',
+    timezone: 'UTC',
+    overlap: 'skip',
+    catchUp: 'one',
+    maxCatchUp: 1,
+    enabled: true,
+    revision: 1,
+    lastFiredAt: 1772420400000
+  }
+}
+```
+
+## What just happened
+
+Four facts in that output are the package working.
+
+- **The first tick fired nothing.** A trigger registered on Sunday evening does
+  not owe Monday morning six days ago. With no `lastFiredAt`, the first tick a
+  process sees establishes a watermark at the latest boundary and starts from
+  the next one.
+- **The idempotency key is the occurrence, not the moment.** It is
+  `<triggerId>:<occurrence ISO instant>`, computed from the schedule boundary
+  with milliseconds zeroed. Two hosts that both notice the same boundary derive
+  the same key, so a duplicate launch is the same launch.
+- **`revision` is 1.** Every registration of the same id bumps the revision, and
+  a claim carries the revision it was computed from. That is the fence that
+  stops a stale snapshot from firing a trigger somebody just edited.
+- **`lastFiredAt` is the occurrence that fired**, not the wall time the host
+  noticed it. It is the cursor catch-up resumes from, and it only ever moves
+  forward, so an older run settling after a newer occurrence was skipped cannot
+  drag it backwards and replay settled work.
+
+## Next steps
+
+- [Run the scheduler in a host](./guides/run-the-scheduler.md): the same
+  composition with a supervisor fiber and the real Control-backed runner.
+- [Choose an overlap and catch-up policy](./guides/choose-a-policy.md): what
+  `skip` and `one` decided here, and when to pick something else.
+- [The claim protocol](./concepts/claim-protocol.md): how hosts coordinate
+  claims and runners deduplicate repeated launch attempts.

package/docs/troubleshooting.md

@@ -0,0 +1,281 @@
+---
+title: "Troubleshooting"
+description: "Every failure code @smthrs/triggers reports, plus the behaviors most often mistaken for bugs: a first tick that fires nothing, a buffer that seems stuck, and a catch-up backlog that was abandoned."
+---
+
+Every failure this package reports is a `TriggerError` carrying a stable `code`.
+Branch on the code; never parse the message. `TriggerError.path` names the
+offending field when the failure could locate one.
+
+Find your code below, or read the last section if nothing failed and the trigger
+still did not do what you expected.
+
+## invalid_cron
+
+**What happened.** Effect's cron parser rejected the expression or the timezone.
+
+**What to change.** Fix the expression. The message is the parser's own, which
+names the field it choked on. A timezone must be an IANA name such as
+`America/New_York`.
+
+## unsatisfiable_cron
+
+**What happened.** The expression parses and the calendar never satisfies it.
+`0 0 30 2 *` is February 30; `0 0 31 4 *` is April 31. The occurrence search
+exhausted its bound looking for a date that does not exist.
+
+**What to change.** Fix the expression. The refusal arrives at declaration time,
+from `Trigger.make`, `Schedule.make`, or `SqlTriggerStore.register`, rather than
+at the tick that would have fired the trigger. That is deliberate: the
+satisfiability probe is the same search every tick performs, so an expression
+that survives declaration is one the scheduler can keep answering.
+
+## invalid_trigger
+
+**What happened.** The declaration did not decode. Either a field is missing or
+the wrong type, or the `input` has no JSON representation.
+
+**What to change.** Read `TriggerError.path`, which names the offending field.
+`id`, `flowId`, and `cron` must be non-empty strings; `maxCatchUp` must be an
+integer between 0 and 1000; `input` must be JSON, which excludes `undefined`,
+`NaN`, a `Date`, and a function.
+
+Enumerable getters are accepted when their values are JSON. They are evaluated
+during decoding and again during SQL serialization. SQL registration takes an
+eager serialized snapshot before returning its Effect; later changes to the
+getter's source do not change that snapshot. Use plain JSON values for stable
+input, since a getter can produce different values or throw on a later read.
+
+## invalid_schedule
+
+**What happened.** The same thing, for a declaration decoded through
+`Schedule.make` rather than `Trigger.make`.
+
+**What to change.** Read `TriggerError.path` and fix the field.
+
+## invalid_options
+
+**What happened.** One of two contracts was violated.
+
+- A cron occurrence limit was not a non-negative safe integer. `path` is
+  `"limit"`, and the message repeats the value it received, including `NaN` and
+  `Infinity`.
+- A scheduler interval or deadline was not a finite, positive Effect duration.
+  `path` is `"pollInterval"`, `"runPollInterval"`, `"startTimeout"`,
+  `"inspectTimeout"`, or `"cancelTimeout"`.
+- A scheduler `concurrency` was not a positive integer. `path` is
+  `"concurrency"`.
+- A `TriggerStore.history` limit was not a positive safe integer. `path` is
+  `"limit"`. Zero is refused here because a zero-row page can never carry a
+  cursor.
+
+**What to change.** Pass a real count, or a real duration. Zero and infinity are
+both refused, because zero polls a CPU-tight loop and infinity never completes,
+and `Duration.fromInput` accepts both.
+
+## catch_up_bound_exceeded
+
+**What happened.** One of three things, and the message tells them apart.
+
+- `maxCatchUp must be a non-negative safe integer, received ...`: the bound
+  itself is unusable. This is checked before any policy branch, so it fires even
+  under `catchUp: "none"`.
+- `missed N occurrences; maxCatchUp is M`: the trigger owes more than it is
+  allowed to replay.
+- `interval contains more than 1000 occurrences`: an unbounded
+  `Cron.occurrencesBetween` was asked for a window it will not materialize.
+
+**What to change.** For an unusable bound, fix the declaration. For a breached
+bound, raise `maxCatchUp`, or accept the abandonment. For an unbounded search,
+pass a `limit`.
+
+The scheduler logs a warning annotated with the trigger id and abandons the
+backlog when catch-up exceeds its bound. It still dispatches the current
+occurrence subject to overlap, on the first poll after a restart and on every
+later poll.
+
+The trap worth naming: `maxCatchUp` defaults to 0, and a declaration that sets
+`catchUp: "one"` without raising it owes one occurrence it is not allowed to
+replay. Whenever `catchUp` is not `none`, set `maxCatchUp` to at least 1. See
+[Choose an overlap and catch-up policy](./guides/choose-a-policy.md).
+
+## unknown_trigger
+
+**What happened.** An operation named a trigger id with no row behind it. Every
+method addressing one trigger reports this, except `clearActive`.
+
+**What to change.** Register the trigger first. If the id is right, check that
+you are pointed at the database you think you are: `SqlTriggerStore.layer`
+creates its tables on the SQL client it is given, so a second in-memory database
+looks exactly like a missing trigger.
+
+## trigger_disabled
+
+**What happened.** A claim read the trigger row inside its transaction and found
+`enabled` false.
+
+**What to change.** Nothing, usually. This is the correct refusal for a
+scheduler that computed an occurrence before somebody disabled the trigger. Note
+that the check is on the stored row, not on the caller's snapshot, so a claim
+built from a stale copy is refused rather than obeyed.
+
+## revision_mismatch
+
+**What happened.** The claim's `expectedRevision` differs from the revision on
+the row. Somebody re-registered the trigger between the read and the claim.
+
+**What to change.** Re-read the trigger and decide again. The scheduler already
+does this: it refreshes once and recomputes what is due from the refreshed
+declaration rather than retrying the occurrence the old one produced, which is
+enough because the next tick reads again anyway.
+
+## verification_failed
+
+**What happened.** A webhook request did not authenticate. Either the signature
+did not match, the header was absent or empty, `SignatureConfig.expected`
+returned zero bytes, or the credential could not be resolved. Nothing was
+decoded and no Control operation ran. The message does not say which: a
+refusal from `Webhook.ingest` always reads `webhook <name> did not verify the
+request`, and one from the signature verifier itself always reads
+`webhook signature in <header> did not verify`. A failure raised by `expected`
+is the verifier refusal's `cause`, so read it there, on the host side, rather
+than expecting it in the message a sender receives.
+
+**What to change.** Check three things in order.
+
+1. The header name in `SignatureConfig.header`. The verifier looks it up first
+   in lowercase and then exactly as written, so a casing mismatch is not the
+   cause, but a wrong name is.
+2. The bytes `SignatureConfig.expected` returns. They are compared against the
+   UTF-8 encoding of the header value, so an implementation that returns raw
+   HMAC bytes where the provider sends hex will never match. Return the encoded
+   form the provider actually sends. A zero-length result is refused outright,
+   because it means the secret resolved to the empty string rather than that
+   every request is valid.
+3. The credential. `Webhook.Config.credential` is required, and a failure inside
+   `expected` while resolving it surfaces here as a typed failure rather than as
+   a defect.
+
+## runner
+
+**What happened.** The scheduler could not plan, launch, inspect, or cancel a
+run, or a plan never got approved.
+
+**What to change.** Read the message.
+
+- `Control plan <id> is still parked awaiting approval after 8 attempts`: the
+  flow needs an approval nobody gave. The runner re-offers the same idempotent
+  request with a delay that doubles from one second, so it gives up a little
+  over two minutes in. Approve the plan, or stop scheduling a flow that requires
+  an interactive approval.
+- `Control rejected the scheduled run: ...`: Control answered `Conflict`. The
+  message is Control's.
+- `Control <tag> receipt did not include a run id`: an accepted launch came back
+  without the id the scheduler needs to monitor it.
+- `Control could not ...`: the underlying Control call failed. The cause carries
+  the original error.
+
+A run inspection error retains the active owner and overlap protection. The
+monitor logs the cause and retries three times with doubling delays starting
+at `runPollInterval`, capped at one minute. Exhaustion detaches the monitor;
+subsequent ticks inspect the retained owner again. Restore Control access to
+resume completion detection. The default run poll interval is fifteen seconds.
+An inspection outage does not record a failed run or cancel it.
+
+## runner_timeout
+
+**What happened.** One `Runner.start`, `inspect`, or `cancel` call exceeded
+`startTimeout`, `inspectTimeout`, or `cancelTimeout`. The defaults are four
+minutes, thirty seconds, and thirty seconds. The call was interrupted.
+
+**What to change.** Nothing is lost. A start that timed out leaves the
+occurrence pending, so the next tick retries it under the same `idempotencyKey`
+and a runtime that did start the run answers with the same run id. An
+inspection that timed out is retried like any inspection failure. A
+cancellation that timed out restores the prior run as active and queues the
+replacement. If the runtime is healthy and merely slow, raise the deadline in
+`Scheduler.Options`; a parked plan needs a `startTimeout` above the two minutes
+`parkedAttempts` allows.
+
+## store
+
+**What happened.** A persistence operation failed, or a `TriggerStore.makeNoop`
+method was called.
+
+**What to change.** Read the message.
+
+- `<method> is unavailable`: the composition provided `TriggerStore.layerNoop`
+  and something reached a method it did not override. Provide a real store, or
+  override that method.
+- `could not run trigger migrations`: the database refused the schema. Check
+  that the SQL client points at a writable database.
+- `could not decode trigger row`: a row's `input_json` did not parse, or the
+  row fails the declaration schema `register` enforces (an empty id, flow, or
+  cron, or a `maxCatchUp` above the limit). Something outside this package
+  wrote the row; the cause names the field.
+- `trigger input is not JSON-serializable`: the input contained a cycle.
+- `trigger store read failed` or `trigger store write failed`: the underlying
+  SQL call failed, and its error is the cause.
+
+## The trigger did not fire, and nothing failed
+
+First ask whether anything is polling. `store.lastHeartbeat()` answers `None`
+when no scheduler has ever ticked against this store, and a `TriggerSummary`
+from `Control.list` carries no `schedulerLastTickMs` in the same case. A
+heartbeat older than `pollInterval` by a wide margin means the scheduler's scope
+closed. Then, four behaviors are correct and surprising.
+
+**A trigger with no durable cursor fires nothing on its first tick.** A trigger with no
+`lastFiredAt` establishes a watermark at the latest boundary on first sight and
+starts from the next one. Registering a weekly trigger on a Sunday evening does
+not fire it for the Monday six days gone. Run a second tick after a boundary has
+passed, or seed a `lastFiredAt` by recording a result.
+
+**A boundary was skipped while a run was in flight.** That is `overlap: "skip"`,
+the default. The occurrence is recorded as `skipped` and the cursor advances.
+Choose `buffer-one` if one coalesced follow-up is enough.
+
+**A buffered occurrence has not run yet.** The buffer drains on the next tick
+after the active run settles, and it holds exactly one occurrence: a run that
+overran four boundaries leaves one pending occurrence, the newest.
+`store.activeRun(triggerId)` tells you whether something is still holding the
+trigger.
+
+**A backlog disappeared after downtime.** Either `catchUp` is `none`, which
+replays no missed boundary, or the backlog exceeded `maxCatchUp` and was
+abandoned with a warning annotated with the trigger id. Check the logs for
+`A trigger abandoned catch-up work beyond its bound`. The current occurrence
+still fires in both cases.
+
+## The trigger fired twice
+
+Check that both launches carry the same `idempotencyKey`. The key is
+`<triggerId>:<occurrence ISO instant>`, so two hosts noticing the same boundary
+produce the same key. Two different keys identify different occurrences or
+trigger ids.
+
+Scheduled dispatch makes at-least-once launch attempts. `RunnerService.start`
+must durably deduplicate by `idempotencyKey` and return the same run identity on
+replay, including across host restarts.
+The Control-backed adapter forwards this key to Control. Custom runners must
+provide the same durable deduplication contract.
+
+The same database can issue another launch-capable claim after lease expiry or
+launch compensation. A launch may have been accepted before its `launched`
+result was persisted; a crash or result-write failure in that window causes a
+retry. An expired lease can also overlap an earlier in-flight attempt. Repeated
+`start` calls with one key are expected during recovery. If they produce
+different run identities, check the runner's durable idempotency records and
+whether the hosts share that deduplication state.
+
+## A run is stuck holding the trigger
+
+A trigger whose `activeRun` never clears is holding either a run the runner
+still calls active, or a launch reservation from a process that died. A
+reservation looks like `trigger-reservation:<triggerId>:<occurrence>`, and
+`TriggerStore.isReservation` says so.
+
+A reservation releases itself when its 5-minute lease expires, at which point
+the store restores the unfinished occurrence to pending work. Wait out the
+lease. A real run id that never clears is a run the control plane still reports
+as live, which is a question for the run, not for the trigger.