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

package/CHANGELOG.md

@@ -0,0 +1,219 @@
+# @smthrs/triggers
+
+## [Unreleased]
+
+### Added
+
+- `TriggerStore.history` reads the fire ledger newest first, filtered by
+  trigger, run, or outcome and paged by cursor and limit, so a listing can show
+  what a trigger did without joining the runtime's run table.
+- `TriggerStore.inspect` reads the run or reservation and the buffered
+  occurrence one trigger holds without expiring anything.
+- `TriggerStore.heartbeat` and `lastHeartbeat`, backed by the
+  `0003_heartbeat` migration, record which scheduler host last polled the
+  store. `Scheduler.Options.host` names the host; `Scheduler.defaultHost` is
+  `"local"`. A heartbeat the store cannot record is logged and the tick goes on.
+- `DispatchReader`, the `@smthrs/control` read port served from a
+  `TriggerStore`, so `Control.list` can answer `triggers` and `fires` from the
+  store the scheduler writes: last fire, buffered occurrence, active run, the
+  next five occurrences, and the newest heartbeat.
+- `TriggerStore.pruneFires({ olderThan })` deletes settled ledger rows older
+  than a cutoff and answers how many it removed, keeping the buffered
+  occurrence and the row naming the active run. Nothing else in the store
+  deletes from `flows_trigger_fires`, so a host that never prunes keeps one row
+  per occurrence for as long as the database lives.
+- `Scheduler.Options.fireRetention`, defaulting to thirty days
+  (`Scheduler.defaultFireRetention`): a tick prunes settled fires older than
+  that at most once an hour. The `0004_fire_run_index` migration indexes the
+  ledger by run id.
+- Daylight-saving tests cover `America/Los_Angeles` and `America/New_York`
+  across both 2026 transitions: weekly Friday series (including one that
+  crosses UTC midnight), a daily time in the spring-forward gap and in the
+  fall-back repeat, an hourly series, and host-zone independence, each through
+  `Cron` and through the scheduler over the SQL store.
+- The scheduler traces `Scheduler.runOnce`, `Scheduler.processTrigger`, and
+  `Scheduler.launch`, and records `smithers.triggers.fires` by outcome plus
+  tick and launch duration histograms (`Scheduler.durationBoundaries`).
+
+### Changed
+
+- `RunnerService.isActive` is replaced by `inspect`, which answers a
+  `RunState`. A run that failed, was cancelled, or is unknown to the runner is
+  recorded as a `failed` fire naming that state; it used to be recorded as
+  `completed`.
+- A tick no longer waits for a launch. The claim is durable and the launch runs
+  on its own fiber, so a plan parked awaiting approval no longer holds other
+  triggers, and a boundary another trigger crosses meanwhile is claimed.
+- The first poll after a restart dispatches the current occurrence even when
+  the backlog exceeds `maxCatchUp` or the policy is `catchUp: "none"`.
+- `DispatchReader.fires` reads only the ledger rows the requested page needs.
+
+- `TriggerStore.list` answers `Listed` rows: the decode result for each row and
+  the state that row holds. A row whose stored input cannot be decoded is
+  isolated there, with its trigger id in the failure, rather than failing the
+  whole listing, so one corrupt declaration no longer stops every healthy
+  schedule in the store on every tick.
+- A scheduler tick reads the listed row before it asks the store again. A
+  trigger holding neither a run nor a buffered occurrence answers `activeRun`
+  and `claimPending` by itself, which cost two write transactions per idle
+  trigger per tick. `DispatchReader.list` takes each summary's held state from
+  the same listing instead of inspecting per trigger.
+- The guides, the claim-protocol concept, and the `Service` documentation say
+  that a tick polls `list` rather than `listEnabled`, because a trigger
+  disabled while a run was active still has to recover that occurrence, and
+  that only claim, result, pending-state, and active-run methods fail with
+  `unknown_trigger`: `get` answers `None` and `register` creates the row.
+
+- Both trigger stores now apply one claim decision. The revision and enabled
+  fences, the expired-reservation reclaim with its supersede predecessor
+  lookup, the three resumable predicates, the cursor advance, and the lease
+  recovery behind `activeRun` were written out once in SQL and again over maps;
+  each store now gathers its snapshot, calls the shared decision, and applies
+  the writes it answers.
+- `test/TestTriggers` registration validates the declaration and serializes its
+  input at the call boundary, the way SQL registration already did, so a
+  declaration mutated after `register` returns cannot change what was stored
+  and an unsatisfiable schedule is refused rather than accepted. Its `list` and
+  `listEnabled` order by id, and every reading is an independent value that
+  cannot be mutated back into stored state.
+- The testing guide, the reference, the claim-protocol concept, and the README
+  state what the in-memory store shares with the SQL store and where it stops:
+  it holds one process's state, reports no `store` write failures, shows no
+  contention between connections, and applies no migrations.
+
+### Fixed
+
+- Daylight saving (#1930). `Cron` now searches wall-clock times and resolves
+  each one in the trigger's zone. A time that spring forward skips fires once,
+  at the instant it would have had on the old offset (a daily 02:30 fires at
+  03:30 daylight time); `previousAtOrBefore` used to fail `unsatisfiable_cron`
+  there, so the scheduler never launched the gap day. A time that fall back
+  repeats fires once, at its first instant; the repeated instant used to match
+  too and launch the day again under a second key. An expression whose hour
+  field is every hour still fires in both passes. Milliseconds are zeroed in
+  UTC; on a host whose own zone was repeating an hour, a matched occurrence
+  used to come back an hour early.
+
+### Removed
+
+- `TriggerStore.takePending`. Nothing dispatched through it: the scheduler
+  takes a buffered occurrence with `claimPending`, which applies the claim
+  fences in the same transaction, and reads one without consuming it through
+  `inspect`. A destructive read beside those was one more method every store
+  had to implement and one more way to drop a buffered occurrence with no
+  claim decision behind it.
+
+## [1.0.0-rc.0] - 2026-09-01
+
+### Added
+
+- Added Effect Cron-backed declarations, overlap and bounded catch-up
+  policies, durable CAS fire claims, a scoped scheduler, authority-free
+  channels, and verified raw-byte webhooks.
+
+### Changed
+
+- A fire claim now carries `expectedRevision` and reads the overlap policy,
+  `enabled`, and `revision` inside the claim transaction, so a caller holding a
+  declaration snapshot from before an edit is refused with `revision_mismatch`
+  or `trigger_disabled` instead of firing it.
+- `TriggerStore.due(now)` is now `TriggerStore.listEnabled()`. The parameter was
+  accepted and discarded; due-ness is a cron computation the scheduler performs
+  against its own watermark.
+- A webhook `credential` is required and is forwarded to `Channel.Verify` and to
+  `Webhook.SignatureConfig.expected` on every request, so a signing secret is
+  resolved through the host resolver rather than captured in a closure at
+  declaration time. `expected` returns an Effect, so a resolution or HMAC
+  failure is a typed `verification_failed` rather than a defect.
+- `Webhook.ingest` copies `body`, `headers`, and `idempotencyKey` before
+  verification, so verification, delivery fingerprinting, and decoding all read
+  one private snapshot. It no longer registers the channel on every request;
+  registration is `Webhook.register`.
+- `Webhook.constantTimeEqual` iterates over the expected signature's length
+  rather than the longer of the two inputs, so its work is fixed by the secret
+  side of the comparison.
+- Error codes gained `runner`, `invalid_options`, `trigger_disabled`, and
+  `revision_mismatch`, and `TriggerError` gained `path`. A declaration failure
+  names its offending field and summarizes the schema issue tree instead of
+  carrying a five-kilobyte AST as its cause.
+- `last_fired_at_ms` only ever moves forward, so an older run settling after a
+  newer occurrence was skipped no longer replays settled work.
+- Scope closure detaches run monitors instead of cancelling them: scheduled runs
+  are durable and the next incarnation re-attaches to them.
+- `Cron.occurrencesBetween` caps an unstated limit at `Cron.maxOccurrences` and
+  refuses a limit that is not a non-negative safe integer.
+- `Schedule.maxCatchUp` defaults to `0` and is bounded above by
+  `Schedule.maxCatchUpLimit`. Every catch-up policy answers to it, `one`
+  included.
+- `TriggerStore.Claim` is a discriminated union: a claim that hands the caller
+  work to launch carries a required `reservationId`, and a claim that only
+  records a decision carries none.
+- `TriggerStore.Service` gained `activeOccurrence(triggerId, runId)`, and
+  `TriggerStore.reservationOccurrence` reads the occurrence out of a reservation
+  id. A recovered run is settled against the occurrence it actually launched,
+  which `lastFiredAt` cannot name once a later occurrence has been skipped or
+  buffered past it.
+- A supersede claim records the run it is displacing on the occurrence that
+  displaced it, so a claimant that dies before it can cancel leaves the
+  predecessor's run id behind for the next incarnation to find.
+- The package documentation is colocated and hand-maintained.
+  `packages/smithers/agent/triggers/README.md`, its `docs/` directory, and the
+  JSDoc in `src/` own the contract. The `docs` and `docsFiles` targets in
+  `PACKAGE.ts` expose them, and `apps/site/scripts/sync-api-docs.mjs` owns the
+  site copy.
+
+### Fixed
+
+- A run held at Control's `accepted` status is no longer recorded as completed
+  on the next poll, which had released the overlap guard for a run that had not
+  started.
+- A newly registered trigger no longer fires an arbitrarily stale past
+  occurrence under `catchUp: "none"`; its first sight establishes the watermark.
+- A launch reservation recovered from the store is no longer cleared on the
+  following tick before its lease expires.
+- The occurrence watermark advances only past occurrences this process finished
+  dispatching, and a buffered occurrence taken from the row is re-armed when the
+  claim or dispatch that followed it failed.
+- `TriggerStore` failures no longer collapse into `store`: a typed refusal the
+  store raised travels out unchanged, and every missing-row path in both the SQL
+  store and the in-memory test layer fails with `unknown_trigger`.
+- A parked plan is re-offered a bounded number of times rather than once a
+  second for the life of the scope, and a scheduler poll interval must be finite
+  and positive.
+- A schema the migrator cannot apply arrives as a typed `store` failure instead
+  of a defect that escapes a constructor whose signature promises
+  `TriggerError`.
+- A launch no longer resolves the wrong `started` handle. An inner binding
+  shadowed the `Deferred` the launch awaits, so `Deferred.succeed` was handed the
+  run id string: every scheduler tick that launched a run waited forever.
+- A recovered launch reservation is re-read from the store on every tick rather
+  than cached as live, so its lease can expire and re-arm the occurrence it
+  holds instead of pinning the trigger until the process restarts.
+- An expired reservation over an occurrence that was claimed but never launched
+  re-arms that occurrence instead of leaving it with no outcome, no active run,
+  and nothing pointing at it.
+- `claimPending` clears the buffer only when the claim it made is not itself a
+  buffer, so an occurrence the overlap policy re-buffers is no longer discarded.
+- A supersede whose cancellation fails restores the run it displaced and queues
+  the replacement occurrence, and it records the terminal result before it
+  detaches the only monitor that could have written one.
+- A launch whose `launched` result cannot be persisted is left to a later poll
+  rather than recorded failed while its run is still executing.
+- A terminal result carrying no run id no longer clears a newer run's active
+  pointer.
+- Coverage thresholds are 100 on all four metrics. The ratchet that stood at
+  68/67/81/80 is what let every defect above ship untested.
+- The CommonJS build no longer hands the migrator `{ default }` objects instead
+  of migration Effects. esbuild compiles a default import of a sibling ESM
+  module to `__toESM(require(...), 1).default`, which under Node interop is the
+  whole exports object, so `require("@smthrs/triggers/SqlTriggerStore")` failed
+  at the first migration. The migration modules export `triggers` and
+  `reservationLease` by name, `migrations/index.ts` imports them by name, and
+  the record is exported as `migrations` so a test can assert each entry has
+  `pipe`.
+
+### Removed
+
+- `@smthrs/triggers/migrations/*` is no longer a public subpath. The intended
+  entry point is `SqlTriggerStore.layer`, which applies both migrations in
+  order.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# @smthrs/triggers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+**Documentation:** https://triggers.smithers.sh
+
+Durable cron triggers and verified inbound channels for flows. A trigger is a
+durable row: a flow id, a JSON input, and a cron expression. A channel is a
+verified door: it authenticates raw request bytes and maps them onto a start or
+a signal.
+
+Nothing here executes a flow. A launch is handed to
+[`@smthrs/control`](https://control.smithers.sh), so a scheduled or webhook
+started run gets exactly the authority a person starting it would get.
+
+## Install
+
+`@smthrs/triggers` is not on npm at 1.0.0-rc.0. It ships as a member of the
+[smithers repository](https://github.com/smithersai/smithers) workspace, so
+using it today means working from a checkout:
+
+```bash
+git clone https://github.com/smithersai/smithers.git
+cd smithers
+pnpm install
+```
+
+It needs Node.js 26.4.0 or later and `effect` 4.0.0-rc.115. The full
+requirements, the import forms, and the layers a running host adds are on
+the [installation page](https://triggers.smithers.sh/installation/).
+
+## The smallest declaration
+
+```ts
+import * as Trigger from "@smthrs/triggers/Trigger"
+
+const nightly = Trigger.make({
+  id: "nightly-report",
+  flowId: "reports/nightly",
+  input: { channel: "#ops" },
+  cron: "0 3 * * *",
+  timezone: "UTC",
+  overlap: "skip",
+  catchUp: "one",
+  maxCatchUp: 1,
+  enabled: true
+})
+```
+
+`nightly` is an `Effect<Trigger, TriggerError>`. `Trigger.make` fills the policy
+defaults and refuses a cron expression the calendar never satisfies. Registering
+it in a `TriggerStore` makes it durable, and a running `Scheduler` fires it from
+there. The [quickstart](https://triggers.smithers.sh/quickstart/) walks that
+whole path, launch included, on a test clock.
+
+## What the package does that a cron loop does not
+
+- Coordinates claims when two hosts share a database. Lease recovery can retry
+  the same occurrence, so preventing duplicate runs requires runner deduplication.
+- Decides what a boundary means while the previous run is still going: skip it,
+  remember the newest one, or cancel the run in flight and replace it.
+- Bounds what a trigger owes after downtime, by a number the declaration states.
+- Accepts an inbound request without handing it authority. A verified payload
+  names a flow; it cannot widen what that flow may do.
+
+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.
+
+## Public API
+
+The root entry point exports these namespaces, and each is also importable from
+`@smthrs/triggers/<Module>`. Every export, with its signature and its
+guarantees, is on the
+[API reference](https://triggers.smithers.sh/reference/api/).
+
+| Namespace         | What it is                                                                                   |
+| ----------------- | -------------------------------------------------------------------------------------------- |
+| `Trigger`         | The trigger declaration: a flow id, a JSON input, a schedule, and an enabled flag.           |
+| `Schedule`        | The reusable schedule half of a declaration: cron, timezone, and the two policies.           |
+| `Cron`            | Typed wrappers around Effect's cron: parse, next, previous, and a bounded occurrence search. |
+| `Overlap`         | The pure decision for an occurrence that arrives while a run is in flight.                   |
+| `CatchUp`         | The pure computation of what a trigger owes after downtime, bounded by its declaration.      |
+| `TriggerStore`    | The durable state contract: registration, listing, the claim protocol, and results.          |
+| `SqlTriggerStore` | The SQLite and PostgreSQL implementation of that contract, with its own migrations.          |
+| `Scheduler`       | The Clock-driven poller, and the `Runner` port it launches through.                          |
+| `DispatchReader`  | The `@smthrs/control` read port served from a store: trigger summaries and the fire ledger.  |
+| `Channel`         | The authority-free inbound channel declaration: verify, then map to a start or a signal.     |
+| `Webhook`         | A verified webhook door built on `Channel`, dispatching only through Control.                |
+| `TriggerError`    | The one failure type, carrying a stable code and an optional field path.                     |
+
+`@smthrs/triggers/test/TestTriggers` is an in-memory `TriggerStore` for tests.
+It applies the same claim decision as the SQL store, with the same refusal
+codes, lease timing, watermark rules, registration validation, and id-ordered
+listings. It keeps no rows and applies no migrations, so a test about a schema
+or a column shape needs `SqlTriggerStore`.
+
+## Documentation
+
+- [Overview](https://triggers.smithers.sh)
+- [Quickstart](https://triggers.smithers.sh/quickstart/)
+- [The claim protocol](https://triggers.smithers.sh/concepts/claim-protocol/)
+- [Choose an overlap and catch-up policy](https://triggers.smithers.sh/guides/choose-a-policy/)
+- [Ingest a verified webhook](https://triggers.smithers.sh/guides/ingest-a-webhook/)
+- [Troubleshooting](https://triggers.smithers.sh/troubleshooting/), which lists
+  every failure code, what causes it, and what to change.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/cjs/CatchUp.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure catch-up policy decisions.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import type { Cron } from "./Cron.ts";
+import type { CatchUp as Policy } from "./Schedule.ts";
+import { TriggerError } from "./TriggerError.ts";
+/**
+ * The occurrences a trigger owes since it last fired, bounded by
+ * `maxCatchUp` and by the policy named in `Schedule.CatchUp`: `none` owes
+ * nothing, `one` owes only the most recent, and `all` owes every missed tick.
+ *
+ * Every policy answers to `maxCatchUp`, `one` included: a bound of zero says
+ * no occurrence may be caught up, so a missed occurrence under `one` is
+ * `catch_up_bound_exceeded` exactly as three missed occurrences under `all`
+ * are. The bound is validated before any policy branch, so an unusable bound
+ * is refused even where the policy owes nothing.
+ *
+ * @category computation
+ * @since 0.1.0
+ */
+export declare const occurrences: (policy: Policy, maxCatchUp: number, lastFiredAt: Date | undefined, now: Date, cron: Cron) => Effect.Effect<ReadonlyArray<Date>, TriggerError>;
+//# sourceMappingURL=CatchUp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CatchUp.d.ts","sourceRoot":"","sources":["../../src/CatchUp.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAErC,OAAO,KAAK,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,eAAe,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAEhD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,MAAM,EACd,YAAY,MAAM,EAClB,aAAa,IAAI,GAAG,SAAS,EAC7B,KAAK,IAAI,EACT,MAAM,IAAI,KACT,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,YAAY,CAwCjD,CAAA"}

package/dist/cjs/CatchUp.js

@@ -0,0 +1,72 @@
+"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 CatchUp_exports = {};
+__export(CatchUp_exports, {
+  occurrences: () => occurrences
+});
+module.exports = __toCommonJS(CatchUp_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var CronSchedule = __toESM(require("./Cron.js"), 1);
+var import_TriggerError = require("./TriggerError.js");
+const occurrences = (policy, maxCatchUp, lastFiredAt, now, cron) => {
+  if (!Number.isSafeInteger(maxCatchUp) || maxCatchUp < 0) {
+    return Effect.fail(
+      new import_TriggerError.TriggerError({
+        code: "catch_up_bound_exceeded",
+        message: `maxCatchUp must be a non-negative safe integer, received ${maxCatchUp}`,
+        path: "maxCatchUp"
+      })
+    );
+  }
+  if (lastFiredAt === void 0) return Effect.succeed([]);
+  if (policy === "none") return Effect.succeed([]);
+  if (policy === "one") {
+    return CronSchedule.previousAtOrBefore(cron, now).pipe(
+      Effect.flatMap(
+        (latest) => latest.getTime() <= lastFiredAt.getTime() ? Effect.succeed([]) : maxCatchUp < 1 ? Effect.fail(
+          new import_TriggerError.TriggerError({
+            code: "catch_up_bound_exceeded",
+            message: `missed 1 occurrence; maxCatchUp is ${maxCatchUp}`
+          })
+        ) : Effect.succeed([latest])
+      )
+    );
+  }
+  return CronSchedule.occurrencesBetween(cron, lastFiredAt, now, maxCatchUp + 1).pipe(
+    Effect.flatMap(
+      (missed) => missed.length > maxCatchUp ? Effect.fail(
+        new import_TriggerError.TriggerError({
+          code: "catch_up_bound_exceeded",
+          message: `missed ${missed.length} occurrences; maxCatchUp is ${maxCatchUp}`
+        })
+      ) : Effect.succeed(missed)
+    )
+  );
+};
+//# sourceMappingURL=CatchUp.js.map

package/dist/cjs/CatchUp.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/CatchUp.ts"],
+  "sourcesContent": ["/**\n * Pure catch-up policy decisions.\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport type { Cron } from \"./Cron.ts\"\nimport * as CronSchedule from \"./Cron.ts\"\nimport type { CatchUp as Policy } from \"./Schedule.ts\"\nimport { TriggerError } from \"./TriggerError.ts\"\n\n/**\n * The occurrences a trigger owes since it last fired, bounded by\n * `maxCatchUp` and by the policy named in `Schedule.CatchUp`: `none` owes\n * nothing, `one` owes only the most recent, and `all` owes every missed tick.\n *\n * Every policy answers to `maxCatchUp`, `one` included: a bound of zero says\n * no occurrence may be caught up, so a missed occurrence under `one` is\n * `catch_up_bound_exceeded` exactly as three missed occurrences under `all`\n * are. The bound is validated before any policy branch, so an unusable bound\n * is refused even where the policy owes nothing.\n *\n * @category computation\n * @since 0.1.0\n */\nexport const occurrences = (\n  policy: Policy,\n  maxCatchUp: number,\n  lastFiredAt: Date | undefined,\n  now: Date,\n  cron: Cron\n): Effect.Effect<ReadonlyArray<Date>, TriggerError> => {\n  if (!Number.isSafeInteger(maxCatchUp) || maxCatchUp < 0) {\n    return Effect.fail(\n      new TriggerError({\n        code: \"catch_up_bound_exceeded\",\n        message: `maxCatchUp must be a non-negative safe integer, received ${maxCatchUp}`,\n        path: \"maxCatchUp\"\n      })\n    )\n  }\n  if (lastFiredAt === undefined) return Effect.succeed([])\n  if (policy === \"none\") return Effect.succeed([])\n  if (policy === \"one\") {\n    return CronSchedule.previousAtOrBefore(cron, now).pipe(\n      Effect.flatMap((latest) =>\n        latest.getTime() <= lastFiredAt.getTime()\n          ? Effect.succeed<ReadonlyArray<Date>>([])\n          : maxCatchUp < 1\n          ? Effect.fail(\n            new TriggerError({\n              code: \"catch_up_bound_exceeded\",\n              message: `missed 1 occurrence; maxCatchUp is ${maxCatchUp}`\n            })\n          )\n          : Effect.succeed<ReadonlyArray<Date>>([latest])\n      )\n    )\n  }\n  return CronSchedule.occurrencesBetween(cron, lastFiredAt, now, maxCatchUp + 1).pipe(\n    Effect.flatMap((missed) =>\n      missed.length > maxCatchUp\n        ? Effect.fail(\n          new TriggerError({\n            code: \"catch_up_bound_exceeded\",\n            message: `missed ${missed.length} occurrences; maxCatchUp is ${maxCatchUp}`\n          })\n        )\n        : Effect.succeed(missed)\n    )\n  )\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,aAAwB;AAExB,mBAA8B;AAE9B,0BAA6B;AAgBtB,MAAM,cAAc,CACzB,QACA,YACA,aACA,KACA,SACqD;AACrD,MAAI,CAAC,OAAO,cAAc,UAAU,KAAK,aAAa,GAAG;AACvD,WAAO,OAAO;AAAA,MACZ,IAAI,iCAAa;AAAA,QACf,MAAM;AAAA,QACN,SAAS,4DAA4D,UAAU;AAAA,QAC/E,MAAM;AAAA,MACR,CAAC;AAAA,IACH;AAAA,EACF;AACA,MAAI,gBAAgB,OAAW,QAAO,OAAO,QAAQ,CAAC,CAAC;AACvD,MAAI,WAAW,OAAQ,QAAO,OAAO,QAAQ,CAAC,CAAC;AAC/C,MAAI,WAAW,OAAO;AACpB,WAAO,aAAa,mBAAmB,MAAM,GAAG,EAAE;AAAA,MAChD,OAAO;AAAA,QAAQ,CAAC,WACd,OAAO,QAAQ,KAAK,YAAY,QAAQ,IACpC,OAAO,QAA6B,CAAC,CAAC,IACtC,aAAa,IACb,OAAO;AAAA,UACP,IAAI,iCAAa;AAAA,YACf,MAAM;AAAA,YACN,SAAS,sCAAsC,UAAU;AAAA,UAC3D,CAAC;AAAA,QACH,IACE,OAAO,QAA6B,CAAC,MAAM,CAAC;AAAA,MAClD;AAAA,IACF;AAAA,EACF;AACA,SAAO,aAAa,mBAAmB,MAAM,aAAa,KAAK,aAAa,CAAC,EAAE;AAAA,IAC7E,OAAO;AAAA,MAAQ,CAAC,WACd,OAAO,SAAS,aACZ,OAAO;AAAA,QACP,IAAI,iCAAa;AAAA,UACf,MAAM;AAAA,UACN,SAAS,UAAU,OAAO,MAAM,+BAA+B,UAAU;AAAA,QAC3E,CAAC;AAAA,MACH,IACE,OAAO,QAAQ,MAAM;AAAA,IAC3B;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/cjs/Channel.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Authority-free channel declarations.
+ *
+ * A channel authenticates opaque transport input, maps verified payloads to
+ * control-plane starts or signals, and may project run state outbound. It
+ * carries no execution authority: the target flow's envelope and permission
+ * checks apply unchanged.
+ *
+ * @see packages/smithers/agent/triggers/docs/api.md
+ * @since 0.1.0
+ */
+import type { IdempotencyKey } from "@smthrs/control/ControlSchema";
+import type { CredentialRef } from "@smthrs/control/Credential";
+import type * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import type * as Schema from "effect/Schema";
+import type { TriggerError } from "./TriggerError.ts";
+/**
+ * Opaque inbound transport data. Verification must inspect this value before
+ * any payload decoding occurs.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RawInbound {
+    readonly body: Uint8Array;
+    readonly headers: Readonly<Record<string, string | undefined>>;
+    readonly idempotencyKey: IdempotencyKey;
+}
+/**
+ * A verified request that starts a flow.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Start {
+    readonly start: {
+        readonly flowId: string;
+        readonly input: unknown;
+    };
+}
+/**
+ * A verified request that resolves a waiting flow step.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Signal {
+    readonly signal: {
+        readonly runId: string;
+        readonly stepId: string;
+        readonly value: unknown;
+    };
+}
+/**
+ * The only operations an inbound channel may request.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Inbound = Start | Signal;
+/**
+ * Authenticates raw request bytes and headers against a credential reference.
+ *
+ * The credential arrives as a redacted reference rather than a secret, and it
+ * arrives per request rather than at declaration time: a verifier resolves it
+ * through the host's resolver when it needs the bytes. Dropping this parameter
+ * left a verifier no way to reach a secret except by closing over it in plain
+ * memory at declaration time, which is the shape the reference exists to
+ * prevent. `packages/smithers/control/src/WebhookChannel.ts` states the same contract
+ * for the control-plane side of the boundary.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Verify = (raw: RawInbound, credential: Redacted.Redacted<CredentialRef>) => Effect.Effect<void, TriggerError>;
+/**
+ * An authority-free bidirectional channel declaration.
+ *
+ * `inbound` only describes a control-plane start or signal. It cannot supply
+ * capabilities, grants, or an alternate execution envelope.
+ *
+ * @category declarations
+ * @since 0.1.0
+ */
+export interface Channel<Payload, Run = never, Outbound = never> {
+    readonly name: string;
+    readonly verify: Verify;
+    readonly inbound: (payload: Payload) => Inbound;
+    readonly outbound?: ((run: Run) => Outbound) | undefined;
+}
+/**
+ * Configuration for a schema-declared channel.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Config<Payload, Run = never, Outbound = never> extends Channel<Payload, Run, Outbound> {
+    readonly schema: Schema.Schema<Payload>;
+}
+/**
+ * Declares a channel without adding authority or execution behavior.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: <Payload, Run = never, Outbound = never>(config: Channel<Payload, Run, Outbound>) => Channel<Payload, Run, Outbound>;
+//# sourceMappingURL=Channel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Channel.d.ts","sourceRoot":"","sources":["../../src/Channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IAC9D,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAA;CACxC;AAED;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KACxB,CAAA;CACF;AAED;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;QACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KACxB,CAAA;CACF;AAED;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,MAAM,CAAA;AAEpC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,MAAM,GAAG,CACnB,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,KACzC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;AAEtC;;;;;;;;GAQG;AACH,MAAM,WAAW,OAAO,CAAC,OAAO,EAAE,GAAG,GAAG,KAAK,EAAE,QAAQ,GAAG,KAAK;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAA;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,QAAQ,CAAC,GAAG,SAAS,CAAA;CACzD;AAED;;;;;GAKG;AACH,MAAM,WAAW,MAAM,CAAC,OAAO,EAAE,GAAG,GAAG,KAAK,EAAE,QAAQ,GAAG,KAAK,CAAE,SAAQ,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC;IACrG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;CACxC;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,EAAE,GAAG,GAAG,KAAK,EAAE,QAAQ,GAAG,KAAK,EACzD,QAAQ,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,KACtC,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAW,CAAA"}

package/dist/cjs/Channel.js

@@ -0,0 +1,25 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Channel_exports = {};
+__export(Channel_exports, {
+  make: () => make
+});
+module.exports = __toCommonJS(Channel_exports);
+const make = (config) => config;
+//# sourceMappingURL=Channel.js.map

package/dist/cjs/Channel.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Channel.ts"],
+  "sourcesContent": ["/**\n * Authority-free channel declarations.\n *\n * A channel authenticates opaque transport input, maps verified payloads to\n * control-plane starts or signals, and may project run state outbound. It\n * carries no execution authority: the target flow's envelope and permission\n * checks apply unchanged.\n *\n * @see packages/smithers/agent/triggers/docs/api.md\n * @since 0.1.0\n */\n\nimport type { IdempotencyKey } from \"@smthrs/control/ControlSchema\"\nimport type { CredentialRef } from \"@smthrs/control/Credential\"\nimport type * as Effect from \"effect/Effect\"\nimport type * as Redacted from \"effect/Redacted\"\nimport type * as Schema from \"effect/Schema\"\nimport type { TriggerError } from \"./TriggerError.ts\"\n\n/**\n * Opaque inbound transport data. Verification must inspect this value before\n * any payload decoding occurs.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface RawInbound {\n  readonly body: Uint8Array\n  readonly headers: Readonly<Record<string, string | undefined>>\n  readonly idempotencyKey: IdempotencyKey\n}\n\n/**\n * A verified request that starts a flow.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Start {\n  readonly start: {\n    readonly flowId: string\n    readonly input: unknown\n  }\n}\n\n/**\n * A verified request that resolves a waiting flow step.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Signal {\n  readonly signal: {\n    readonly runId: string\n    readonly stepId: string\n    readonly value: unknown\n  }\n}\n\n/**\n * The only operations an inbound channel may request.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Inbound = Start | Signal\n\n/**\n * Authenticates raw request bytes and headers against a credential reference.\n *\n * The credential arrives as a redacted reference rather than a secret, and it\n * arrives per request rather than at declaration time: a verifier resolves it\n * through the host's resolver when it needs the bytes. Dropping this parameter\n * left a verifier no way to reach a secret except by closing over it in plain\n * memory at declaration time, which is the shape the reference exists to\n * prevent. `packages/smithers/control/src/WebhookChannel.ts` states the same contract\n * for the control-plane side of the boundary.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Verify = (\n  raw: RawInbound,\n  credential: Redacted.Redacted<CredentialRef>\n) => Effect.Effect<void, TriggerError>\n\n/**\n * An authority-free bidirectional channel declaration.\n *\n * `inbound` only describes a control-plane start or signal. It cannot supply\n * capabilities, grants, or an alternate execution envelope.\n *\n * @category declarations\n * @since 0.1.0\n */\nexport interface Channel<Payload, Run = never, Outbound = never> {\n  readonly name: string\n  readonly verify: Verify\n  readonly inbound: (payload: Payload) => Inbound\n  readonly outbound?: ((run: Run) => Outbound) | undefined\n}\n\n/**\n * Configuration for a schema-declared channel.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Config<Payload, Run = never, Outbound = never> extends Channel<Payload, Run, Outbound> {\n  readonly schema: Schema.Schema<Payload>\n}\n\n/**\n * Declares a channel without adding authority or execution behavior.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <Payload, Run = never, Outbound = never>(\n  config: Channel<Payload, Run, Outbound>\n): Channel<Payload, Run, Outbound> => config\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAsHO,MAAM,OAAO,CAClB,WACoC;",
+  "names": []
+}