@objectstack/trigger-schedule 17.0.0 → 17.2.0

package/CHANGELOG.md

@@ -1,5 +1,244 @@
 # @objectstack/plugin-trigger-schedule
 
+## 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
+
+- Updated dependencies [56656aa]
+- Updated dependencies [07e630e]
+- Updated dependencies [2f65b1b]
+- Updated dependencies [720ee95]
+- Updated dependencies [f287435]
+- Updated dependencies [2782805]
+- Updated dependencies [e43d63a]
+- Updated dependencies [9aa8890]
+- Updated dependencies [7c9c1dd]
+- Updated dependencies [75b7c24]
+- Updated dependencies [d5552ca]
+- Updated dependencies [d9813a9]
+- Updated dependencies [8640fb2]
+- Updated dependencies [2420641]
+- Updated dependencies [2ad91c3]
+- Updated dependencies [f57fb38]
+- Updated dependencies [00777a0]
+- Updated dependencies [d491625]
+- Updated dependencies [420804d]
+- Updated dependencies [716ac9b]
+- Updated dependencies [a38408a]
+- Updated dependencies [62b1427]
+- Updated dependencies [7ea1372]
+- Updated dependencies [23abe27]
+- Updated dependencies [985a9cd]
+- Updated dependencies [5f5e234]
+- Updated dependencies [a8189ae]
+- Updated dependencies [26e70fb]
+- Updated dependencies [42b05af]
+- Updated dependencies [2b292ce]
+- Updated dependencies [abcf853]
+- Updated dependencies [8b9eba5]
+- Updated dependencies [d575779]
+- Updated dependencies [94f7ef8]
+- Updated dependencies [c5ac5e4]
+- Updated dependencies [a777944]
+- Updated dependencies [dd88e1c]
+- Updated dependencies [856527c]
+- Updated dependencies [870f710]
+- Updated dependencies [79c46da]
+- Updated dependencies [7ff3975]
+- Updated dependencies [29d055b]
+- Updated dependencies [65589d6]
+- Updated dependencies [2c86fe3]
+- Updated dependencies [e196c6a]
+- Updated dependencies [24173e9]
+- Updated dependencies [4ab7523]
+- Updated dependencies [19539b4]
+- Updated dependencies [f8eb736]
+- Updated dependencies [11b779e]
+- Updated dependencies [739fe5b]
+- Updated dependencies [4bfe1a5]
+- Updated dependencies [2065e31]
+- Updated dependencies [b69d0f5]
+- Updated dependencies [4d47afe]
+- Updated dependencies [e4e5c6e]
+- Updated dependencies [9a56784]
+- Updated dependencies [d00d2f6]
+- Updated dependencies [df0c12d]
+- Updated dependencies [d31785f]
+- Updated dependencies [c308a4f]
+- Updated dependencies [e2899f6]
+- Updated dependencies [3851f87]
+- Updated dependencies [2a29caa]
+- Updated dependencies [09a6eee]
+- Updated dependencies [1a7f907]
+- Updated dependencies [cd455c8]
+- Updated dependencies [e1bb0ca]
+- Updated dependencies [30d3752]
+- Updated dependencies [c80e7ae]
+- Updated dependencies [09a9a8a]
+- Updated dependencies [07026cf]
+- Updated dependencies [5d4f3d5]
+- Updated dependencies [4d80e8b]
+- Updated dependencies [30b1c63]
+- Updated dependencies [079b457]
+- Updated dependencies [e43b211]
+- Updated dependencies [890b38f]
+- Updated dependencies [8bee54b]
+- Updated dependencies [7a537ce]
+- Updated dependencies [593c4bf]
+- Updated dependencies [ff08691]
+- Updated dependencies [60e0f90]
+- Updated dependencies [90c5285]
+- Updated dependencies [402c125]
+- Updated dependencies [7901b2d]
+- Updated dependencies [56bca91]
+- Updated dependencies [79394d7]
+- Updated dependencies [730fd9a]
+- Updated dependencies [44bc51d]
+- Updated dependencies [73cfddf]
+- Updated dependencies [d634e66]
+  - @objectstack/spec@17.1.0
+  - @objectstack/core@17.1.0
+
 ## 17.0.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

@@ -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 };

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -26,6 +26,7 @@ __export(index_exports, {
   TimeRelativeTriggerPlugin: () => TimeRelativeTriggerPlugin,
   buildWindowWhere: () => buildWindowWhere,
   computeDateWindows: () => computeDateWindows,
+  computeWindowClaimScopes: () => computeWindowClaimScopes,
   normalizeSchedule: () => normalizeSchedule
 });
 module.exports = __toCommonJS(index_exports);
@@ -179,6 +180,7 @@ var ScheduleTriggerPlugin = class {
 var import_automation = require("@objectstack/spec/automation");
 var JOB_PREFIX2 = "flow-time-relative";
 var MS_PER_DAY = 864e5;
+var LOCAL_CLAIM_TTL_MS = 48 * 60 * 60 * 1e3;
 function startOfUtcDay(d) {
   return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), 0, 0, 0, 0));
 }
@@ -189,18 +191,21 @@ function addUtcDays(d, n) {
   return new Date(startOfUtcDay(d).getTime() + n * MS_PER_DAY);
 }
 function computeDateWindows(desc, now) {
+  return computeWindowClaimScopes(desc, now).map((s) => s.window);
+}
+function computeWindowClaimScopes(desc, now) {
   const today = startOfUtcDay(now);
   if (desc.offsetDays && desc.offsetDays.length > 0) {
     return desc.offsetDays.map((offset) => {
       const day = addUtcDays(today, offset);
-      return { gte: startOfUtcDay(day).toISOString(), lte: endOfUtcDay(day).toISOString() };
+      const window2 = { gte: startOfUtcDay(day).toISOString(), lte: endOfUtcDay(day).toISOString() };
+      return { window: window2, scope: `${window2.gte.slice(0, 10)}:offset${offset}` };
     });
   }
   const n = desc.withinDays ?? 0;
-  if (n >= 0) {
-    return [{ gte: startOfUtcDay(today).toISOString(), lte: endOfUtcDay(addUtcDays(today, n)).toISOString() }];
-  }
-  return [{ gte: startOfUtcDay(addUtcDays(today, n)).toISOString(), lte: endOfUtcDay(today).toISOString() }];
+  const sweepDay = today.toISOString().slice(0, 10);
+  const window = n >= 0 ? { gte: startOfUtcDay(today).toISOString(), lte: endOfUtcDay(addUtcDays(today, n)).toISOString() } : { gte: startOfUtcDay(addUtcDays(today, n)).toISOString(), lte: endOfUtcDay(today).toISOString() };
+  return [{ window, scope: `${sweepDay}:within${n}` }];
 }
 function buildWindowWhere(desc, window) {
   return {
@@ -212,14 +217,23 @@ function errMessage(err) {
   return err?.message ?? String(err);
 }
 var TimeRelativeTrigger = class {
-  constructor(getJobService, getDataEngine, logger, now = () => /* @__PURE__ */ new Date()) {
+  constructor(getJobService, getDataEngine, logger, now = () => /* @__PURE__ */ new Date(), getClaimSurface = () => null) {
     this.type = "time_relative";
     /** flowName → job name registered for it, so stop() can cancel it. */
     this.bound = /* @__PURE__ */ new Map();
+    /**
+     * 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.
+     */
+    this.localClaims = /* @__PURE__ */ new Map();
+    /** Whether the in-process-only dedup degradation has been said (once). */
+    this.claimDegradationWarned = false;
     this.getJobService = getJobService;
     this.getDataEngine = getDataEngine;
     this.logger = logger;
     this.now = now;
+    this.getClaimSurface = getClaimSurface;
   }
   start(binding, callback) {
     const raw = binding.config?.timeRelative;
@@ -289,10 +303,10 @@ var TimeRelativeTrigger = class {
       );
       return;
     }
-    const windows = computeDateWindows(desc, this.now());
+    const scopes = computeWindowClaimScopes(desc, this.now());
     const seenIds = /* @__PURE__ */ new Set();
     const matched = [];
-    for (const window of windows) {
+    for (const { window, scope } of scopes) {
       if (matched.length >= maxRecords) break;
       const where = buildWindowWhere(desc, window);
       const rows = await engine.find(desc.object, {
@@ -306,7 +320,8 @@ var TimeRelativeTrigger = class {
           if (seenIds.has(id)) continue;
           seenIds.add(id);
         }
-        matched.push(row);
+        const claimKey = id != null ? `time-relative:${flowName}:${scope}:${String(id)}` : null;
+        matched.push({ record: row, claimKey });
         if (matched.length >= maxRecords) break;
       }
     }
@@ -317,7 +332,12 @@ var TimeRelativeTrigger = class {
     }
     let launched = 0;
     let failed = 0;
-    for (const record of matched) {
+    let deduped = 0;
+    for (const { record, claimKey } of matched) {
+      if (claimKey != null && !await this.claimDispatch(flowName, claimKey)) {
+        deduped++;
+        continue;
+      }
       try {
         const ctx = {
           record,
@@ -339,9 +359,51 @@ var TimeRelativeTrigger = class {
       }
     }
     this.logger.debug?.(
-      `[time-relative] flow '${flowName}' swept '${desc.object}': ${matched.length} matched, ${launched} launched, ${failed} failed`
+      `[time-relative] flow '${flowName}' swept '${desc.object}': ${matched.length} matched, ${launched} launched, ${deduped} already dispatched, ${failed} failed`
     );
   }
+  /**
+   * 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.
+   */
+  async claimDispatch(flowName, key) {
+    const surface = this.getClaimSurface();
+    if (surface && typeof surface.claim === "function") {
+      try {
+        return await surface.claim(key);
+      } catch (err) {
+        this.logger.warn(
+          `[time-relative] flow '${flowName}' dispatch-claim failed for key '${key}' \u2014 dispatching anyway (availability over strict-once; the same window may re-fire until the claim store recovers): ${errMessage(err)}`
+        );
+        return true;
+      }
+    }
+    if (!this.claimDegradationWarned) {
+      this.claimDegradationWarned = true;
+      this.logger.warn(
+        `[time-relative] no dispatch-claim surface (automation service missing or without claim()) \u2014 sweep dedup is IN-PROCESS ONLY and will NOT survive a kernel rebuild: the same record/window can re-fire after a restart.`
+      );
+    }
+    const now = this.now().getTime();
+    const cutoff = now - LOCAL_CLAIM_TTL_MS;
+    for (const [k, t] of this.localClaims) {
+      if (t < cutoff) this.localClaims.delete(k);
+    }
+    if (this.localClaims.has(key)) return false;
+    this.localClaims.set(key, now);
+    return true;
+  }
   stop(flowName) {
     const jobName = this.bound.get(flowName);
     if (!jobName) return;
@@ -389,7 +451,18 @@ var TimeRelativeTriggerPlugin = class {
       const trigger = new TimeRelativeTrigger(
         () => this.resolveService(ctx, "job"),
         () => this.resolveDataEngine(ctx),
-        ctx.logger
+        ctx.logger,
+        void 0,
+        // default wall clock
+        // #10220 — dispatch-idempotency claims go through the SAME
+        // automation service this plugin already resolves; the trigger
+        // computes the key and never learns the ledger's table name. An
+        // automation service predating claim() resolves to null and the
+        // trigger degrades (honestly, warned once) to in-process dedup.
+        () => {
+          const svc = this.resolveService(ctx, "automation");
+          return svc && typeof svc.claim === "function" ? svc : null;
+        }
       );
       automation.registerTrigger(trigger);
       ctx.logger.info("TimeRelativeTriggerPlugin: time-relative trigger registered");
@@ -414,6 +487,7 @@ var TimeRelativeTriggerPlugin = class {
   TimeRelativeTriggerPlugin,
   buildWindowWhere,
   computeDateWindows,
+  computeWindowClaimScopes,
   normalizeSchedule
 });
 //# sourceMappingURL=index.js.map