@objectstack/trigger-schedule 17.1.0 → 17.3.0

package/CHANGELOG.md

@@ -1,5 +1,434 @@
 # @objectstack/plugin-trigger-schedule
 
+## 17.3.0
+
+### Patch Changes
+
+- Updated dependencies [809d417]
+- Updated dependencies [387e231]
+- Updated dependencies [f794e4e]
+- Updated dependencies [cae2169]
+- Updated dependencies [b812a54]
+- Updated dependencies [2d4fa75]
+- Updated dependencies [0e4e51b]
+- Updated dependencies [e84bbf6]
+- Updated dependencies [effae80]
+- Updated dependencies [efb3513]
+- Updated dependencies [d62f990]
+- Updated dependencies [c45d8e6]
+- Updated dependencies [2e3e8c7]
+- Updated dependencies [e621291]
+- Updated dependencies [655b106]
+- Updated dependencies [40a93b5]
+- Updated dependencies [d5b330d]
+- Updated dependencies [dda969c]
+- Updated dependencies [1f45690]
+- Updated dependencies [277948f]
+- Updated dependencies [8bdd955]
+- Updated dependencies [f3bbbef]
+- Updated dependencies [4f24e9d]
+- Updated dependencies [e27583e]
+- Updated dependencies [4bd6faa]
+- Updated dependencies [86cbe37]
+- Updated dependencies [6a180e4]
+- Updated dependencies [474242f]
+- Updated dependencies [63cd487]
+- Updated dependencies [bd4aa4e]
+- Updated dependencies [803eaab]
+- Updated dependencies [f8e8f03]
+- Updated dependencies [983edf1]
+- Updated dependencies [eae824e]
+- Updated dependencies [f6fa22c]
+- Updated dependencies [8a483b3]
+- Updated dependencies [97bcd99]
+- Updated dependencies [df59de0]
+- Updated dependencies [96e25a8]
+- Updated dependencies [f75a38a]
+- Updated dependencies [7a25e7d]
+- Updated dependencies [1fa05a6]
+- Updated dependencies [c85a265]
+- Updated dependencies [dcb10a5]
+- Updated dependencies [773a999]
+- Updated dependencies [35dffea]
+- Updated dependencies [d8024f0]
+- Updated dependencies [8120808]
+- Updated dependencies [776a098]
+- Updated dependencies [5060877]
+- Updated dependencies [4f6325d]
+- Updated dependencies [52954c0]
+- Updated dependencies [2aa8456]
+- Updated dependencies [93809a3]
+- Updated dependencies [7c0d0c3]
+- Updated dependencies [daae7aa]
+- Updated dependencies [8dc22d6]
+- Updated dependencies [279431e]
+- Updated dependencies [948dd6b]
+- Updated dependencies [3b4c56c]
+- Updated dependencies [ae8edd2]
+- Updated dependencies [e25403c]
+- Updated dependencies [64baa68]
+- Updated dependencies [9fa70d7]
+- Updated dependencies [09db64a]
+- Updated dependencies [92916e7]
+- Updated dependencies [a84f3ea]
+- Updated dependencies [f2eaae8]
+- Updated dependencies [c09451b]
+- Updated dependencies [ba64877]
+- Updated dependencies [7345308]
+- Updated dependencies [79b6a22]
+- Updated dependencies [30d96ab]
+- Updated dependencies [f658793]
+- Updated dependencies [c95ad19]
+- Updated dependencies [e58ea8b]
+- Updated dependencies [4a17645]
+- Updated dependencies [3795c5f]
+- Updated dependencies [8ab926b]
+- Updated dependencies [7317cf2]
+- Updated dependencies [e25e839]
+- Updated dependencies [5997207]
+- Updated dependencies [8b13cc8]
+- Updated dependencies [4a4a35d]
+- Updated dependencies [86e765a]
+- Updated dependencies [1d7e76a]
+- Updated dependencies [53dc739]
+- Updated dependencies [fd289be]
+- Updated dependencies [03bf7b1]
+- Updated dependencies [f90e820]
+- Updated dependencies [18d816a]
+- Updated dependencies [e8bd715]
+- Updated dependencies [b91c351]
+- Updated dependencies [a28a3c0]
+- Updated dependencies [daeaaf9]
+- Updated dependencies [c459da6]
+- Updated dependencies [e914733]
+- Updated dependencies [f887e52]
+- Updated dependencies [881f8d8]
+- Updated dependencies [3bfa1e6]
+- Updated dependencies [0a8ebf3]
+- Updated dependencies [901355c]
+- Updated dependencies [34ce8e7]
+- Updated dependencies [33681ea]
+- Updated dependencies [4635f3e]
+- Updated dependencies [fd289be]
+- Updated dependencies [ee3595c]
+- Updated dependencies [b2eab95]
+- Updated dependencies [93940d4]
+- Updated dependencies [3a04b01]
+- Updated dependencies [45b9051]
+- Updated dependencies [b9e9227]
+- Updated dependencies [d395692]
+- Updated dependencies [5894d30]
+- Updated dependencies [a3765f6]
+- Updated dependencies [2d5cee3]
+- Updated dependencies [e22158f]
+- Updated dependencies [7404925]
+- Updated dependencies [0c2334f]
+- Updated dependencies [778c59f]
+- Updated dependencies [d2619fd]
+- Updated dependencies [af56546]
+- Updated dependencies [6acb11a]
+- Updated dependencies [33c5fd3]
+- Updated dependencies [20b0fdb]
+- Updated dependencies [905019b]
+- Updated dependencies [a286411]
+- Updated dependencies [98c0d33]
+- Updated dependencies [368a82e]
+- Updated dependencies [a3d5724]
+- Updated dependencies [93ea19b]
+- Updated dependencies [9ee2dcf]
+- Updated dependencies [8cb96ec]
+- Updated dependencies [8f10a79]
+- Updated dependencies [6269a55]
+- Updated dependencies [a17da05]
+- Updated dependencies [a8c00e2]
+- Updated dependencies [0fb8760]
+- Updated dependencies [e5ce2ed]
+- Updated dependencies [be21955]
+- Updated dependencies [bc56e18]
+- Updated dependencies [be21955]
+- Updated dependencies [a9ee989]
+- Updated dependencies [4d0d944]
+- Updated dependencies [15d58db]
+- Updated dependencies [d63b014]
+- Updated dependencies [9abe4e4]
+- Updated dependencies [2cc7122]
+- Updated dependencies [50d6c92]
+- Updated dependencies [9e0ba21]
+- Updated dependencies [311433f]
+- Updated dependencies [3e5ad08]
+- Updated dependencies [9abe4e4]
+- Updated dependencies [b7131f3]
+- Updated dependencies [e5812fa]
+- Updated dependencies [7085f90]
+- Updated dependencies [dee4dd4]
+- Updated dependencies [ce7e497]
+- Updated dependencies [51ecb2f]
+- Updated dependencies [9086761]
+- Updated dependencies [42a117b]
+- Updated dependencies [1401ae7]
+- Updated dependencies [4297fe7]
+- Updated dependencies [e398863]
+- Updated dependencies [d16df74]
+- Updated dependencies [f11fc61]
+- Updated dependencies [e808890]
+- Updated dependencies [8f79379]
+- Updated dependencies [e6ca40e]
+- Updated dependencies [0c77ea4]
+- Updated dependencies [52954c0]
+- Updated dependencies [89eb997]
+- Updated dependencies [7131f12]
+- Updated dependencies [aa5994e]
+- Updated dependencies [be93457]
+- Updated dependencies [a65db76]
+- Updated dependencies [15eb2c9]
+- Updated dependencies [5691b07]
+- Updated dependencies [2a6122b]
+- Updated dependencies [225e769]
+- Updated dependencies [8af88dd]
+- Updated dependencies [fb5fbb8]
+- Updated dependencies [d7b3963]
+- Updated dependencies [33184fd]
+- Updated dependencies [7c41693]
+- Updated dependencies [b72db01]
+- Updated dependencies [dce5cd4]
+- Updated dependencies [9688f58]
+- Updated dependencies [556ebc1]
+- Updated dependencies [177ebdc]
+- Updated dependencies [8d237b4]
+- Updated dependencies [2d2e6f0]
+- Updated dependencies [2d8dd8d]
+- Updated dependencies [22d573e]
+- Updated dependencies [b5a2398]
+- Updated dependencies [348860c]
+- Updated dependencies [5383fa6]
+- Updated dependencies [5b3ff63]
+- Updated dependencies [1a6a19c]
+- Updated dependencies [527e050]
+- Updated dependencies [dd33bf9]
+- Updated dependencies [4cb2a90]
+- Updated dependencies [74a7804]
+- Updated dependencies [53d3689]
+- Updated dependencies [b3a63d3]
+- Updated dependencies [49f0dcf]
+- Updated dependencies [033a34c]
+- Updated dependencies [4d25d22]
+- Updated dependencies [1ffee51]
+- Updated dependencies [5ae4303]
+- Updated dependencies [ece4dad]
+- Updated dependencies [e9b377e]
+- Updated dependencies [146f448]
+- Updated dependencies [735f5c7]
+- Updated dependencies [a7e18de]
+- Updated dependencies [366f895]
+- Updated dependencies [dc75ba8]
+- Updated dependencies [cce0aa9]
+- Updated dependencies [e764507]
+- Updated dependencies [cff17af]
+- Updated dependencies [39404f3]
+- Updated dependencies [ca1965f]
+- Updated dependencies [8619f95]
+- Updated dependencies [b706af9]
+- Updated dependencies [add4360]
+- Updated dependencies [fc9ba76]
+- Updated dependencies [0f94cc7]
+- Updated dependencies [a11c1a5]
+- Updated dependencies [71f9cd1]
+- Updated dependencies [ee17d86]
+- Updated dependencies [cdbd920]
+- Updated dependencies [18c432e]
+- Updated dependencies [3c418c4]
+- Updated dependencies [fa8715a]
+- Updated dependencies [a933ed7]
+- Updated dependencies [b3ca463]
+- Updated dependencies [a933ed7]
+- Updated dependencies [0d4a6a8]
+- Updated dependencies [518d5e5]
+- Updated dependencies [6643ba1]
+- Updated dependencies [eeba2ef]
+- Updated dependencies [ec4c4d2]
+- Updated dependencies [424f73c]
+- Updated dependencies [cccbe51]
+- Updated dependencies [a8d6b1d]
+- Updated dependencies [e4a7695]
+- Updated dependencies [87075b1]
+- Updated dependencies [fc58a99]
+- Updated dependencies [14cfc00]
+- Updated dependencies [1c6f7b4]
+- Updated dependencies [e854a53]
+- Updated dependencies [dfebfc8]
+- Updated dependencies [d028b37]
+- Updated dependencies [f7b25c5]
+- Updated dependencies [122ef38]
+- Updated dependencies [4a37870]
+- Updated dependencies [428f9b2]
+- Updated dependencies [aa7ff56]
+- Updated dependencies [c41b42e]
+- Updated dependencies [c4db311]
+- Updated dependencies [750fff5]
+- Updated dependencies [c19035e]
+- Updated dependencies [ececf7a]
+- Updated dependencies [d173125]
+- Updated dependencies [8eeca27]
+- Updated dependencies [8425c17]
+- Updated dependencies [a5ef1d8]
+- Updated dependencies [772d5de]
+- Updated dependencies [ce80ec2]
+- Updated dependencies [b372318]
+- Updated dependencies [97a2263]
+- Updated dependencies [29d0676]
+- Updated dependencies [0169d49]
+- Updated dependencies [6bd3231]
+- Updated dependencies [d2b5ba8]
+- Updated dependencies [b799ac5]
+- Updated dependencies [8f74307]
+- Updated dependencies [d23dc08]
+- Updated dependencies [644ad50]
+- Updated dependencies [0da7cd2]
+- Updated dependencies [28a5c3e]
+- Updated dependencies [4bc18e5]
+  - @objectstack/spec@17.3.0
+  - @objectstack/core@17.3.0
+
+## 17.2.0
+
+### Minor Changes
+
+- 73d9795: Time-relative sweeps are now idempotent per matched window (#10220). Previously the sweep
+  held no cross-tick memory, so every re-scan of the same window re-dispatched the same
+  records — a 5s-interval flow minted 15 duplicate reminders in ~70s, and even under a daily
+  cron a kernel rebuild re-dispatched the day's window.
+  
+  - `@objectstack/service-automation` — new platform object `sys_flow_dispatch`: a persisted
+    dispatch-claim ledger (ADR-0057 telemetry retention, 30 days), registered alongside
+    `sys_automation_run` and exposed as `AutomationEngine.claim(key): Promise<boolean>` on
+    the automation service surface (check-and-record; a concurrent duplicate insert re-reads
+    and reports the key as already claimed). When no ObjectQL engine / registration is
+    available the engine degrades to in-process dedup and logs the weakened guarantee once;
+    when the ledger errors, the claim falls back to the in-process check for that key so a
+    store outage never blocks a dispatch (availability over strict-once).
+  - `@objectstack/trigger-schedule` — the time-relative sweep computes a dispatch key from
+    the MATCHED WINDOW's identity and claims it before launching: offset mode keys on
+    `(flowName, recordId, windowDay, offset)` — so a dateField edit that moves the window
+    legitimately re-fires — and range mode keys on `(flowName, recordId, sweepDay,
+    rangeSpec)`, preserving the documented `withinDays` semantic ("fires every day the
+    record stays in range") while never firing twice in one day. The trigger resolves the
+    claim surface structurally from the automation service; without one it dedups
+    in-process and warns once.
+  - `@objectstack/spec` — `sys_flow_dispatch` added to `PLATFORM_OBJECTS_BY_PACKAGE` under
+    `service-automation` (registry conformance).
+
+### Patch Changes
+
+- 6ceaa4b: docs: name packages that exist in seven published documents, and gate the class (#10893)
+  
+  A published README ships inside the npm tarball, so an install instruction in one
+  reaches every reader of the package. Nine `@objectstack/` names across seven
+  published documents named a package that is in **no directory of this repo**, and
+  five of those sat on `import` lines inside runnable fences.
+  
+  `check:published-readme-exports` could not see any of it, by construction. It
+  resolves a documented import against the package's built type surface through the
+  workspace member map, so a specifier that is not a member has no type entry to
+  compare against and the gate reads no further — strict about a member that exists,
+  silent about one that does not. The gate now makes the member-existence claim
+  first: an `@objectstack/`-scoped specifier that names no workspace member is a
+  finding, and the run header prints the scoped population as `N/N` so a recogniser
+  that stops matching shows up as a denominator that fell.
+  
+  What each dead claim now says, and why:
+  
+  - **`@objectstack/trigger-schedule`** and **`@objectstack/trigger-record-change`**
+    each misnamed **themselves**. Both READMEs — including their `# ` titles and
+    every fenced import — said `@objectstack/plugin-trigger-…`, a name that has
+    never been published. The exported class names (`ScheduleTriggerPlugin`,
+    `TimeRelativeTriggerPlugin`, `RecordChangeTriggerPlugin`) were correct all
+    along; only the package name was wrong, so this is a rename pinned by each
+    package's own `name` field.
+  - **`@objectstack/plugin-security`** told readers to `install
+    @objectstack/plugin-org-scoping` and register an `OrgScopingPlugin` from it. No
+    such package exists. The organization wall ships as the enterprise
+    `@objectstack/organizations` runtime, whose `OrganizationsPlugin` registers the
+    `org-scoping` service this plugin probes — the name `objectstack serve` and
+    `objectstack doctor` both print. Asking for the wall without it is a refusal to
+    boot (ADR-0093 D5), not a silent downgrade, and the page now says so. The
+    tenant-isolation bullet pointed at `@objectstack/service-tenant`, which is the
+    cloud control-plane runtime from the separate `cloud` repository and not where
+    the wall comes from either.
+  - **`@objectstack/service-package`** described packages being "delivered to
+    runtime kernels that load them through `@objectstack/service-marketplace`". That
+    package was never built: ADR-0003, ADR-0016 and ADR-0025 all name it as future
+    work. The loading half that does exist here is
+    `@objectstack/cloud-connection`'s `MarketplaceInstallLocalPlugin`.
+  - **`@objectstack/embedder-openai`** had a fenced example importing
+    `KnowledgeTursoPlugin` from `@objectstack/knowledge-turso` — the worst shape,
+    because a reader pastes it. No knowledge adapter in this repository consumes an
+    `IEmbedder` at all: `knowledge-memory` and `knowledge-ragflow` take no embedder
+    option, and the adapters the contract is written for are not here. The example
+    is now the `embed()` surface that does exist, with the gap stated rather than
+    papered over with a substitute package name.
+  - **`@objectstack/driver-sqlite-wasm`**'s "When to use" table compared it against
+    `@objectstack/driver-sqlite` and `@objectstack/driver-postgres`. Neither has
+    ever existed; `@objectstack/driver-sql` covers PostgreSQL, MySQL and SQLite
+    through Knex, choosing the client from its optional peers.
+  - **`@objectstack/spec`**'s published `prompts/architecture.md` instructed code
+    generators to write `import { User } from '@objectstack/protocol'`. The package
+    is `@objectstack/spec`, which the same sentence names as the path being
+    replaced.
+  
+  Four `@objectstack/` names that are **not** in this repo are deliberately left as
+  they are, because prose may name a package this repo does not build and a runnable
+  import may not: `@objectstack/security-enterprise` (the enterprise edition, whose
+  install hint the CLI prints and a CLI test pins), `@objectstack/service-tenant`
+  (the cloud runtime), `@objectstack/framework` (the umbrella install name), and the
+  two names `service-datasource`'s README recalls as its own past.
+- Updated dependencies [6936d07]
+- Updated dependencies [59eb04d]
+- Updated dependencies [9f05b7d]
+- Updated dependencies [3b2af5e]
+- Updated dependencies [7d2d112]
+- Updated dependencies [5fa0d72]
+- Updated dependencies [02b3b07]
+- Updated dependencies [914c413]
+- Updated dependencies [55809a0]
+- Updated dependencies [ee2ff45]
+- Updated dependencies [47cd3ec]
+- Updated dependencies [52db1d1]
+- Updated dependencies [5649efb]
+- Updated dependencies [9d7d2de]
+- Updated dependencies [c815c50]
+- Updated dependencies [795ea05]
+- Updated dependencies [2306a76]
+- Updated dependencies [e5ea701]
+- Updated dependencies [a40dcc1]
+- Updated dependencies [def0d3e]
+- Updated dependencies [8d0bb79]
+- Updated dependencies [5acb58d]
+- Updated dependencies [2e3cf95]
+- Updated dependencies [4c93387]
+- Updated dependencies [504c8d5]
+- Updated dependencies [a037f7c]
+- Updated dependencies [3ee8ddf]
+- Updated dependencies [16cef97]
+- Updated dependencies [a79bd35]
+- Updated dependencies [6ceaa4b]
+- Updated dependencies [15ea214]
+- Updated dependencies [de19489]
+- Updated dependencies [c684d00]
+- Updated dependencies [923c424]
+- Updated dependencies [1ec36b7]
+- Updated dependencies [5f2e54c]
+- Updated dependencies [189373b]
+- Updated dependencies [35ad101]
+- Updated dependencies [ceb33a9]
+- Updated dependencies [73d9795]
+- Updated dependencies [8012960]
+- Updated dependencies [f34f56b]
+- Updated dependencies [f399618]
+- Updated dependencies [75e9301]
+- Updated dependencies [2810695]
+  - @objectstack/spec@17.2.0
+  - @objectstack/core@17.2.0
+
 ## 17.1.0
 
 ### Patch Changes

package/README.md

@@ -1,4 +1,4 @@
-# @objectstack/plugin-trigger-schedule
+# @objectstack/trigger-schedule
 
 Auto-launch ObjectStack flows on a schedule (cron / interval / once).
 
@@ -9,7 +9,7 @@ platform `IJobService` (the `'job'` service), so it stays adapter-agnostic: the
 job service selects a cron-capable adapter (e.g. the durable `DbJobAdapter` or
 `CronJobAdapter`) for cron schedules and the interval adapter for the rest.
 
-This is the sibling of `@objectstack/plugin-trigger-record-change` — same
+This is the sibling of `@objectstack/trigger-record-change` — same
 engine baseline, a different event source.
 
 ## What it does
@@ -48,7 +48,7 @@ in its context.
 ```ts
 import { AutomationServicePlugin } from '@objectstack/service-automation';
 import { JobServicePlugin } from '@objectstack/service-job';
-import { ScheduleTriggerPlugin } from '@objectstack/plugin-trigger-schedule';
+import { ScheduleTriggerPlugin } from '@objectstack/trigger-schedule';
 
 kernel
   .use(new AutomationServicePlugin())  // engine + flows
@@ -110,7 +110,7 @@ It needs both the job service (sweep cadence) **and** the ObjectQL engine (the
 date-window query); register it alongside the schedule trigger:
 
 ```ts
-import { ScheduleTriggerPlugin, TimeRelativeTriggerPlugin } from '@objectstack/plugin-trigger-schedule';
+import { ScheduleTriggerPlugin, TimeRelativeTriggerPlugin } from '@objectstack/trigger-schedule';
 
 kernel
   .use(new ScheduleTriggerPlugin())      // plain schedule flows

package/dist/index.d.mts

@@ -23,7 +23,7 @@ import { TimeRelativeTrigger as TimeRelativeTrigger$1 } from '@objectstack/spec/
  */
 declare class ScheduleTriggerPlugin implements Plugin {
     name: string;
-    type: string;
+    type: "standard";
     version: string;
     dependencies: string[];
     init(ctx: PluginContext): Promise<void>;
@@ -136,7 +136,7 @@ declare class ScheduleTrigger implements FlowTrigger {
  */
 declare class TimeRelativeTriggerPlugin implements Plugin {
     name: string;
-    type: string;
+    type: "standard";
     version: string;
     dependencies: string[];
     init(ctx: PluginContext): Promise<void>;
@@ -170,6 +170,18 @@ interface TimeRelativeDataEngine {
      */
     getObject?(name: string): unknown;
 }
+/**
+ * The slice of the automation service this trigger needs for dispatch
+ * idempotency (#10220): claim a dispatch key against the persisted
+ * `sys_flow_dispatch` ledger. `true` = this caller owns the dispatch; `false` =
+ * an earlier sweep (possibly in a previous process lifetime) already made it.
+ * Typed structurally — like {@link TimeRelativeDataEngine} — so this plugin
+ * never learns the ledger's table name and takes no build dependency on
+ * `@objectstack/service-automation`.
+ */
+interface FlowDispatchClaimSurface {
+    claim(key: string): Promise<boolean>;
+}
 /** A closed, inclusive instant window `[gte, lte]` as ISO-8601 strings. */
 interface DateWindow {
     /** Lower bound (inclusive), ISO-8601. */
@@ -190,6 +202,32 @@ interface DateWindow {
  * `date` field (compared as `YYYY-MM-DD` after the driver truncates) is inclusive.
  */
 declare function computeDateWindows(desc: TimeRelativeTrigger$1, now: Date): DateWindow[];
+/**
+ * A date window paired with the **claim scope** naming its identity for the
+ * dispatch dedup key (#10220, maintainer ruling 2026-08-20).
+ */
+interface WindowClaimScope {
+    window: DateWindow;
+    /**
+     * Window-identity fragment of the dispatch key — what makes a re-scan of
+     * the SAME window dedup while a genuinely new window fires again:
+     *
+     * - offset mode → `<windowDay>:offset<n>`: the window day is the date the
+     *   record's field must fall on, so editing the field to a new day (or a
+     *   different offset matching) yields a new key and legitimately re-fires.
+     *   Re-scans of one window all derive the same day → deduped.
+     * - range mode → `<sweepDay>:within<n>`: keyed on the SWEEP day, not the
+     *   (constant) field value, so the documented `withinDays` semantic —
+     *   "fires every day the record stays in range" — remains true: each new
+     *   day is a new key, but never twice in one day.
+     */
+    scope: string;
+}
+/**
+ * {@link computeDateWindows}, with each window's claim scope (#10220). One
+ * derivation for both so the matching rule and the dedup key can never drift.
+ */
+declare function computeWindowClaimScopes(desc: TimeRelativeTrigger$1, now: Date): WindowClaimScope[];
 /**
  * Build the ObjectQL `where` map for one date window: the descriptor's static
  * `filter` (if any) ANDed with a `$gte`/`$lte` range on the date field. The map
@@ -229,7 +267,17 @@ declare class TimeRelativeTrigger implements FlowTrigger {
     private readonly now;
     /** flowName → job name registered for it, so stop() can cancel it. */
     private readonly bound;
-    constructor(getJobService: () => JobServiceSurface | null, getDataEngine: () => TimeRelativeDataEngine | null, logger: TriggerLogger, now?: () => Date);
+    /** Dispatch-idempotency claim surface (#10220), resolved lazily per sweep. */
+    private readonly getClaimSurface;
+    /**
+     * In-process claim fallback when no claim surface resolves (#10220):
+     * key → claim time (epoch ms), TTL-pruned. Dedups re-scans within THIS
+     * process only — which is why falling to it is warned once, below.
+     */
+    private readonly localClaims;
+    /** Whether the in-process-only dedup degradation has been said (once). */
+    private claimDegradationWarned;
+    constructor(getJobService: () => JobServiceSurface | null, getDataEngine: () => TimeRelativeDataEngine | null, logger: TriggerLogger, now?: () => Date, getClaimSurface?: () => FlowDispatchClaimSurface | null);
     start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void;
     /**
      * Run one sweep: query each date window, union the matched records (deduped
@@ -237,7 +285,23 @@ declare class TimeRelativeTrigger implements FlowTrigger {
      * per-record failure is isolated so one bad row never aborts the batch.
      */
     private sweep;
+    /**
+     * Claim one dispatch key (#10220): `true` = launch, `false` = an earlier
+     * sweep already dispatched this (flow, record, window).
+     *
+     * Degradation contract:
+     *  - Claim surface resolves (the automation service's `claim()`, backed by
+     *    the persisted `sys_flow_dispatch` ledger) → its answer is used; if the
+     *    CALL throws, the failure is logged and the dispatch proceeds —
+     *    availability over strict-once: a broken ledger must never silently
+     *    swallow reminders.
+     *  - No claim surface (automation service missing, or one predating
+     *    `claim()`) → in-process dedup only, warned ONCE: a silent fallback
+     *    would hide that the once-per-window guarantee no longer survives a
+     *    kernel rebuild.
+     */
+    private claimDispatch;
     stop(flowName: string): void;
 }
 
-export { type DateWindow, type FlowTrigger, type FlowTriggerBinding, type JobServiceSurface, ScheduleTrigger, ScheduleTriggerPlugin, type TimeRelativeDataEngine, TimeRelativeTrigger, TimeRelativeTriggerPlugin, type TriggerLogger, buildWindowWhere, computeDateWindows, normalizeSchedule };
+export { type DateWindow, type FlowDispatchClaimSurface, type FlowTrigger, type FlowTriggerBinding, type JobServiceSurface, ScheduleTrigger, ScheduleTriggerPlugin, type TimeRelativeDataEngine, TimeRelativeTrigger, TimeRelativeTriggerPlugin, type TriggerLogger, type WindowClaimScope, buildWindowWhere, computeDateWindows, computeWindowClaimScopes, normalizeSchedule };