@objectstack/trigger-schedule 17.3.0 → 17.4.0

package/CHANGELOG.md

@@ -1,5 +1,195 @@
 # @objectstack/plugin-trigger-schedule
 
+## 17.4.0
+
+### Minor Changes
+
+- 8341ed2: A scheduled (cron) flow is now delivered once per tick window, and replaying a window that was already delivered is refused instead of silently sent again.
+  
+  A `time_relative` flow has taken a persisted dispatch claim per `(flow, window, record)` since #10220, so per-record once-only delivery is free for it. A `schedule` flow runs once per tick with no record and had no claim surface at all, so "this batch already went out" fell back to whatever each app remembered for itself. A scheduled digest that was replayed by an operator, or whose process restarted inside its window, delivered twice.
+  
+  Scheduled flows now claim `(flow, tick-window)` in the same `sys_flow_dispatch` ledger, and settle that claim with what the run turned into:
+  
+  - **A second fire inside one window does nothing.** The window key is a pure function of the schedule descriptor and the clock — the previous occurrence of the very same cron expression in the very same timezone, computed with the same library the job adapter schedules with — so a restart inside the window computes the same key and hits the same claim.
+  - **`IJobService.replay()` refuses a delivered window**, with the ADR-0112 envelope its contract declares: `code: 'RESOURCE_CONFLICT'`, `status: 409`, and a message naming the window and the claim that refused it. The promise rejects — an operator who presses replay and sees nothing happen is exactly the outcome this replaces.
+  - **`replay(name, data, { force: true })` sends anyway.** The duplicate is the operator's, taken knowingly.
+  - **A window whose claim is absent, failed or unsettled re-runs** on a plain `replay()`, with no force needed. A job that takes no claim at all — every job that is not a scheduled flow — is the absent row and behaves exactly as before.
+  - **`succeeded` is absorbing.** A replay that repairs a failed window records `succeeded`, so the next unforced replay is refused. A *forced* replay that throws leaves the window recorded delivered rather than rewriting it to `failed` — otherwise a failed re-send would silently reopen the unforced re-delivery door. An operator whose forced replay failed forces again.
+  - **A `once` schedule now has a tick window too** — the single instant it is due, which is one window for the job's whole life. The visible consequence is on replay: an operator who replays a one-shot job *before* its due instant claims that single window, so the real fire then finds the claim and does nothing. Previously both ran.
+  
+  The error-isolation `catch` that keeps a throwing flow from crashing the ticker is unchanged and still swallows. What it no longer does is leave the run indistinguishable from a delivered one: the throw settles the window's claim as `failed`, so a replay repairs it.
+  
+  `sys_flow_dispatch` gains two optional columns, `outcome` and `settled_at`. Rows written before this release read as unsettled, which reads as not delivered — the safe direction, since a replay of one re-runs rather than being refused. Only `schedule:` claims are ever settled; a `time_relative` sweep's rows stay `null` by design.
+  
+  ⚠️ **If you manage this table's DDL out of band** — anything other than letting the platform sync `sys_flow_dispatch` from its object definition — add `outcome` (text) and `settled_at` (datetime) yourself before upgrading. Without them every `settle()` throws against the driver. Dispatch dedup still works and no flow fails (the settle is best-effort and logged), but no claim ever records an outcome, so the replay refusal never fires and this release's headline change is silently absent.
+  
+  Interface changes for hosts that implement the ledger themselves:
+  
+  - `FlowDispatchStore` gains **optional** `settle()` and `read()`. A store without them still deduplicates; it announces once that the refusal cannot fire.
+  - `FlowDispatchStoreEngine` — the narrow ObjectQL slice the bundled store demands — now **requires** `update` alongside `find` and `insert`. A custom engine adapter typed against it must add the method.
+  - New exported types: `FlowDispatchClaim` and `FlowDispatchOutcome` from `@objectstack/service-automation`; `ReplayGuard` and `ReplayGuardDecision` from `@objectstack/service-job` (the parameter type of `DbJobAdapter.setReplayGuard`, exported so it can be named); `ScheduleDispatchLedger`, `ScheduleDispatchClaim`, `ScheduleDispatchOutcome`, `ReplayGuard` and `ReplayGuardDecision` from `@objectstack/trigger-schedule`.
+  - `croner` moves from a devDependency to a **dependency** of `@objectstack/trigger-schedule`, which now imports it at runtime to compute the cron tick window. It is already a runtime dependency of `@objectstack/service-job` at the same range, so the platform's dependency set does not grow.
+
+### Patch Changes
+
+- b224324: `@objectstack/trigger-record-change` and `@objectstack/trigger-schedule` now declare a `repository.directory` that resolves to the directory they actually live in.
+  
+  Both manifests declared a path under `packages/plugins/` that no longer exists in the repository:
+  
+  | package | declared | actual |
+  |---|---|---|
+  | `@objectstack/trigger-record-change` | `packages/plugins/plugin-trigger-record-change` | `packages/triggers/trigger-record-change` |
+  | `@objectstack/trigger-schedule` | `packages/plugins/plugin-trigger-schedule` | `packages/triggers/trigger-schedule` |
+  
+  `repository.directory` is what npm uses to build the **Repository** deep link on a package page, and what tooling uses to locate a monorepo package's source from its tarball. Pointing it at a path that does not exist sends a reader to a 404 instead of to the source — on packages published today at `17.3.0`. The value ships inside the tarball, so this correction only reaches npm by being published; that is why it carries a changeset rather than `skip-changeset`.
+  
+  The residue came from a three-commit sequence on 2026-06-12, and only one of those commits was a pure rename. `f15d6f6f6` **copied** the two packages to `packages/plugins/trigger-*` (26 files, +2222/-19, with all four directories briefly coexisting) and edited exactly one line of each copied manifest — its `name` — leaving `directory` pointing at the path it was copied from; `290c62514` deleted the originals five minutes later; and `ea4941ad8` then promoted `packages/plugins/trigger-*` to a first-class `packages/triggers/` directory as a pure 16-file rename with zero content changes, which made the declared value wrong in a second segment. Six weeks after that, `9a43e042f` (#3380) rewrote `repository.url` and `bugs` in both of these manifests, with the stale `directory` line sitting as unchanged context one line below the edited `url`. So the field was not merely never in anyone's way: one commit edited its immediate neighbour inside the same object, and a later reviewed hunk had the wrong line on screen. Nothing caught it because nothing reads it.
+  
+  Scope of this change, stated as a measured set rather than a general claim: over all **81** tracked `package.json` files in the repository, **57** declare `repository.directory`; before this change **55** resolved to the manifest's own directory and **2** did not — the two above. After it, **57 of 57** resolve. No other manifest field is edited, and no package's code, exports or behaviour is touched. The remaining **24** manifests declare no `repository.directory` at all; that population is deliberately left alone here and is reported separately, because whether declaring the field is mandatory is a policy question rather than a correction.
+- Updated dependencies [fe0d9a4]
+- Updated dependencies [ecd2158]
+- Updated dependencies [f2b5e46]
+- Updated dependencies [2ed6be6]
+- Updated dependencies [ed7243d]
+- Updated dependencies [6ba0db4]
+- Updated dependencies [625b0c3]
+- Updated dependencies [233222e]
+- Updated dependencies [07f40e5]
+- Updated dependencies [ceb4877]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [90e7e6d]
+- Updated dependencies [2bdabe6]
+- Updated dependencies [ca326b5]
+- Updated dependencies [8f404a5]
+- Updated dependencies [68437d4]
+- Updated dependencies [abb140c]
+- Updated dependencies [8333a6c]
+- Updated dependencies [3e3ecb0]
+- Updated dependencies [3030369]
+- Updated dependencies [d5d8d50]
+- Updated dependencies [e08892d]
+- Updated dependencies [ae05f2e]
+- Updated dependencies [b548e43]
+- Updated dependencies [c463d03]
+- Updated dependencies [64bd6a3]
+- Updated dependencies [13c48c2]
+- Updated dependencies [b0529e1]
+- Updated dependencies [66dc6ab]
+- Updated dependencies [6f94458]
+- Updated dependencies [6e67b86]
+- Updated dependencies [132742f]
+- Updated dependencies [85a2459]
+- Updated dependencies [50dc214]
+- Updated dependencies [e89fa92]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [8976ea1]
+- Updated dependencies [56fe8c2]
+- Updated dependencies [acabd24]
+- Updated dependencies [ab50c8f]
+- Updated dependencies [6491463]
+- Updated dependencies [89cf4d6]
+- Updated dependencies [21c5dcb]
+- Updated dependencies [6d4d5d3]
+- Updated dependencies [ed5d557]
+- Updated dependencies [bca21f7]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [2025b1f]
+- Updated dependencies [1a7a7c9]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [ef3a138]
+- Updated dependencies [68d5dfd]
+- Updated dependencies [3e21cf0]
+- Updated dependencies [4cfc93b]
+- Updated dependencies [efd6b43]
+- Updated dependencies [859ded3]
+- Updated dependencies [fa125f3]
+- Updated dependencies [74628d9]
+- Updated dependencies [a646120]
+- Updated dependencies [6f1ce7d]
+- Updated dependencies [7778115]
+- Updated dependencies [2c753fe]
+- Updated dependencies [52804cd]
+- Updated dependencies [3f89967]
+- Updated dependencies [53cf263]
+- Updated dependencies [21aabbc]
+- Updated dependencies [9c270bb]
+- Updated dependencies [76c8c5a]
+- Updated dependencies [a84e1ce]
+- Updated dependencies [bf1054a]
+- Updated dependencies [d8d2776]
+- Updated dependencies [222dc0f]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [32c917d]
+- Updated dependencies [f9a3c32]
+- Updated dependencies [f502898]
+- Updated dependencies [51ae731]
+- Updated dependencies [af7edfe]
+- Updated dependencies [b60f48b]
+- Updated dependencies [c78c918]
+- Updated dependencies [cf9bda4]
+- Updated dependencies [784cb92]
+- Updated dependencies [7629f4d]
+- Updated dependencies [51df9fd]
+- Updated dependencies [a7da4de]
+- Updated dependencies [de0bcdd]
+- Updated dependencies [70f7d6d]
+- Updated dependencies [c677cda]
+- Updated dependencies [554a160]
+- Updated dependencies [f7da71e]
+- Updated dependencies [7f745c3]
+- Updated dependencies [5eb24f8]
+- Updated dependencies [2a3decc]
+- Updated dependencies [cc00df2]
+- Updated dependencies [cc00df2]
+- Updated dependencies [f4e6adf]
+- Updated dependencies [ee4a59b]
+- Updated dependencies [4db3c61]
+- Updated dependencies [5ca314a]
+- Updated dependencies [e0af1a8]
+- Updated dependencies [4771bd9]
+- Updated dependencies [414c1fc]
+- Updated dependencies [22c0279]
+- Updated dependencies [0db2947]
+- Updated dependencies [92b5d7f]
+- Updated dependencies [613bfbd]
+- Updated dependencies [abae16a]
+- Updated dependencies [094b8fd]
+- Updated dependencies [c7aca0d]
+- Updated dependencies [c1d8f98]
+- Updated dependencies [8e0b297]
+- Updated dependencies [d4f9b2a]
+- Updated dependencies [5f7fa1d]
+- Updated dependencies [87f0ccc]
+- Updated dependencies [aedbaef]
+- Updated dependencies [a727043]
+- Updated dependencies [c5d6803]
+- Updated dependencies [10d05bb]
+- Updated dependencies [69602e5]
+- Updated dependencies [c3ce76c]
+- Updated dependencies [7936b29]
+- Updated dependencies [46803fa]
+- Updated dependencies [c2a336c]
+- Updated dependencies [9f890d3]
+- Updated dependencies [0bb2318]
+- Updated dependencies [f7db8f4]
+- Updated dependencies [1ecee3e]
+- Updated dependencies [9408b7f]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [9bcd9be]
+- Updated dependencies [b398ad2]
+- Updated dependencies [99261a7]
+- Updated dependencies [81b426f]
+- Updated dependencies [001af1c]
+- Updated dependencies [fb77aa5]
+- Updated dependencies [581d8f8]
+- Updated dependencies [f81afe3]
+- Updated dependencies [40a44b9]
+- Updated dependencies [f89812e]
+- Updated dependencies [7a7fb03]
+- Updated dependencies [8fd246d]
+  - @objectstack/spec@17.4.0
+  - @objectstack/core@17.4.0
+
 ## 17.3.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -61,14 +61,71 @@ interface FlowTrigger {
     start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void;
     stop(flowName: string): void;
 }
+/**
+ * What a {@link ReplayGuard} answers when a job service is about to replay a
+ * job it does not itself understand. Structural mirror of the job adapter's
+ * own type — see the note on {@link JobServiceSurface}.
+ */
+type ReplayGuardDecision = {
+    readonly allow: true;
+} | {
+    readonly allow: false;
+    /** Human-readable identity of the window that was already delivered. */
+    readonly window: string;
+    /** When that window's claim was taken (ISO-8601), if the ledger knows. */
+    readonly claimedAt: string | null;
+};
+/**
+ * A per-job pre-flight the job service runs before `replay()` (#14501).
+ *
+ * It is asked, and it also PREPARES: a guard that answers `{ allow: true }`
+ * has already armed whatever its owner needs to let the replayed run through
+ * its own idempotency gate. So a job service must call it exactly once per
+ * replay, and must not call it for a replay it then abandons.
+ */
+type ReplayGuard = (options: {
+    readonly force: boolean;
+}) => Promise<ReplayGuardDecision>;
 /**
  * The slice of `IJobService` this trigger needs: schedule a named job and
  * cancel it. Typed structurally so the plugin depends on the spec contract
  * shape, not a concrete adapter.
+ *
+ * `setReplayGuard` is OPTIONAL and is NOT part of the `IJobService` spec
+ * contract — it is the adapter-local registration `DbJobAdapter` grew for
+ * #14501, and a job service without it (the bootstrap `IntervalJobAdapter`,
+ * any third-party adapter) simply never installs the guard. That degradation
+ * is declared, not silent: see {@link ScheduleTrigger} for what is lost.
  */
 interface JobServiceSurface {
     schedule(name: string, schedule: JobSchedule, handler: JobHandler): Promise<void>;
     cancel(name: string): Promise<void>;
+    setReplayGuard?(name: string, guard: ReplayGuard | null): void;
+}
+/** What a claimed dispatch turned into — mirror of the ledger's own type. */
+type ScheduleDispatchOutcome = 'succeeded' | 'failed';
+/** One dispatch-claim row, as this trigger reads it back. */
+interface ScheduleDispatchClaim {
+    readonly outcome: ScheduleDispatchOutcome | null;
+    readonly claimedAt: string | null;
+}
+/**
+ * The slice of the automation service this trigger needs for once-per-window
+ * delivery (#14501): the same `sys_flow_dispatch` claim ledger the
+ * time-relative trigger uses for its per-record keys (#10220), plus the
+ * outcome half the #14501 ruling added.
+ *
+ * Typed structurally — like {@link JobServiceSurface} — so this plugin never
+ * learns the ledger's table name and takes no build dependency on
+ * `@objectstack/service-automation`. `settleDispatch` / `readDispatch` are
+ * optional for the same reason `claim` is resolved defensively: an automation
+ * service predating either one resolves to a partial surface, and the trigger
+ * degrades honestly rather than throwing at bind time.
+ */
+interface ScheduleDispatchLedger {
+    claim(key: string): Promise<boolean>;
+    settleDispatch?(key: string, outcome: ScheduleDispatchOutcome): Promise<void>;
+    readDispatch?(key: string): Promise<ScheduleDispatchClaim | null>;
 }
 /** Minimal logger surface (matches core's `ctx.logger`). */
 interface TriggerLogger {
@@ -105,6 +162,26 @@ declare function normalizeSchedule(raw: unknown): JobSchedule | null;
  * The job service is resolved lazily (per `start()`) via the supplied accessor,
  * so we always pick up the job service's *upgraded* adapter (e.g. the durable
  * DbJobAdapter that replaces the bootstrap interval adapter on `kernel:ready`).
+ *
+ * ## Once-per-window delivery (#14501)
+ *
+ * A scheduled flow claims a `(flow, tick-window)` key in the shared
+ * `sys_flow_dispatch` ledger before it launches, and settles that claim with
+ * the run's outcome afterwards — the same ledger the time-relative trigger
+ * claims per `(flow, record, window)` (#10220), with the key shape the
+ * maintainer's A + a2 ruling named. Three doors close at once:
+ *
+ *  - a second tick inside one window finds the claim and does nothing;
+ *  - a restart inside a window is that same case, because the key is a pure
+ *    function of the schedule descriptor and the clock, not of process state;
+ *  - an operator `replay()` of a window that was DELIVERED is refused with an
+ *    ADR-0112 `RESOURCE_CONFLICT` / 409 envelope, via the
+ *    {@link ReplayGuard} this trigger registers on the job service.
+ *
+ * What did NOT change is the error isolation: a throwing flow is still caught
+ * and swallowed so the ticker survives. It stopped being SILENT — the throw
+ * settles the window's claim `failed`, and a plain `replay()` re-runs a failed
+ * window — but the ticker's protection is unchanged and must stay that way.
  */
 declare class ScheduleTrigger implements FlowTrigger {
     readonly type = "schedule";
@@ -112,8 +189,77 @@ declare class ScheduleTrigger implements FlowTrigger {
     private readonly logger;
     /** flowName → job name registered for it, so stop() can cancel it. */
     private readonly bound;
-    constructor(getJobService: () => JobServiceSurface | null, logger: TriggerLogger);
+    /** Dispatch-claim ledger (#14501), resolved lazily per fire. */
+    private readonly getLedger;
+    /** Injectable clock so window math is deterministic under test. */
+    private readonly now;
+    /**
+     * flowName → the ONE dispatch key a {@link ReplayGuard} has authorised for
+     * re-dispatch (#14501). A replay of a window whose claim is absent or
+     * failed must actually re-run it — but the handler's own claim gate would
+     * see the existing row and no-op, so the guard leaves a one-shot pass here
+     * and the handler consumes it. In-process by construction and correctly
+     * so: the pass is written and read inside a single `replay()` call chain.
+     *
+     * Keyed by FLOW rather than accumulated in a set, so a pass a job service
+     * asked for and then abandoned is overwritten by the next one instead of
+     * outliving its window — at most one outstanding pass per bound flow, and
+     * `stop()` takes it with the binding.
+     *
+     * ⚠️ Residue is therefore bounded but not zero: an abandoned pass survives
+     * until this flow's next guard call replaces it, or `stop()` drops it. A
+     * later fire does NOT clear it — the handler deletes the entry only when
+     * the pass MATCHES the window it just computed — so an abandoned pass
+     * outlives every fire in every other window. It stays inert through all of
+     * them for the same reason: a pass naming a window that has passed can
+     * never match again. Its blast radius is one fire of one flow inside the
+     * window the pass names, and only if that window is still current — a fire
+     * that would have been a no-op runs instead.
+     */
+    private readonly replayPasses;
+    /** Whether the in-process-only dedup degradation has been said (once). */
+    private claimDegradationWarned;
+    /** Whether the "no replay guard could be installed" degradation has been said (once). */
+    private replayGuardDegradationWarned;
+    constructor(getJobService: () => JobServiceSurface | null, logger: TriggerLogger, getLedger?: () => ScheduleDispatchLedger | null, now?: () => Date);
     start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void;
+    /**
+     * Install the `replay()` pre-flight for this job (#14501), when the job
+     * service has somewhere to put one.
+     *
+     * Degradation contract, declared once: a job service without
+     * `setReplayGuard` (the bootstrap `IntervalJobAdapter`, any adapter
+     * predating #14501) keeps every other guarantee here — a second tick in a
+     * window is still a no-op, a throw is still recorded failed — but an
+     * operator replay of a DELIVERED window can no longer be refused loudly.
+     * It hits the handler's claim gate and returns having done nothing, which
+     * is the silent no-op the ruling exists to prevent, so it is said out loud
+     * here instead.
+     *
+     * ⚠ Said only when a ledger is actually attached. With no ledger nothing is
+     * ever RECORDED as delivered, so there is no refusal to lose and the line
+     * would be a false alarm — that deployment's real degradation is the
+     * "delivery is NOT deduplicated" warning {@link claimDispatch} already
+     * emits, and stacking a second, vacuous warning on top of it buries the
+     * one that matters.
+     */
+    private installReplayGuard;
+    /**
+     * Claim one `(flow, tick-window)` dispatch key (#14501): `true` = launch,
+     * `false` = this window was already dispatched (an earlier tick this
+     * process, or a previous process lifetime).
+     *
+     * Degradation contract, deliberately identical to the time-relative
+     * trigger's: a ledger call that THROWS dispatches anyway (availability
+     * over strict-once — a broken ledger must never silently swallow a
+     * digest), and a missing ledger is warned once because the once-per-window
+     * guarantee then no longer survives a kernel rebuild.
+     */
+    private claimDispatch;
+    /** Record what a dispatch turned into. Best-effort: never fails the run. */
+    private settleDispatch;
+    /** Read one dispatch claim. A ledger that cannot answer reports `null`. */
+    private readDispatch;
     stop(flowName: string): void;
 }
 
@@ -304,4 +450,4 @@ declare class TimeRelativeTrigger implements FlowTrigger {
     stop(flowName: string): void;
 }
 
-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 };
+export { type DateWindow, type FlowDispatchClaimSurface, type FlowTrigger, type FlowTriggerBinding, type JobServiceSurface, type ReplayGuard, type ReplayGuardDecision, type ScheduleDispatchClaim, type ScheduleDispatchLedger, type ScheduleDispatchOutcome, ScheduleTrigger, ScheduleTriggerPlugin, type TimeRelativeDataEngine, TimeRelativeTrigger, TimeRelativeTriggerPlugin, type TriggerLogger, type WindowClaimScope, buildWindowWhere, computeDateWindows, computeWindowClaimScopes, normalizeSchedule };

package/dist/index.d.ts

@@ -61,14 +61,71 @@ interface FlowTrigger {
     start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void;
     stop(flowName: string): void;
 }
+/**
+ * What a {@link ReplayGuard} answers when a job service is about to replay a
+ * job it does not itself understand. Structural mirror of the job adapter's
+ * own type — see the note on {@link JobServiceSurface}.
+ */
+type ReplayGuardDecision = {
+    readonly allow: true;
+} | {
+    readonly allow: false;
+    /** Human-readable identity of the window that was already delivered. */
+    readonly window: string;
+    /** When that window's claim was taken (ISO-8601), if the ledger knows. */
+    readonly claimedAt: string | null;
+};
+/**
+ * A per-job pre-flight the job service runs before `replay()` (#14501).
+ *
+ * It is asked, and it also PREPARES: a guard that answers `{ allow: true }`
+ * has already armed whatever its owner needs to let the replayed run through
+ * its own idempotency gate. So a job service must call it exactly once per
+ * replay, and must not call it for a replay it then abandons.
+ */
+type ReplayGuard = (options: {
+    readonly force: boolean;
+}) => Promise<ReplayGuardDecision>;
 /**
  * The slice of `IJobService` this trigger needs: schedule a named job and
  * cancel it. Typed structurally so the plugin depends on the spec contract
  * shape, not a concrete adapter.
+ *
+ * `setReplayGuard` is OPTIONAL and is NOT part of the `IJobService` spec
+ * contract — it is the adapter-local registration `DbJobAdapter` grew for
+ * #14501, and a job service without it (the bootstrap `IntervalJobAdapter`,
+ * any third-party adapter) simply never installs the guard. That degradation
+ * is declared, not silent: see {@link ScheduleTrigger} for what is lost.
  */
 interface JobServiceSurface {
     schedule(name: string, schedule: JobSchedule, handler: JobHandler): Promise<void>;
     cancel(name: string): Promise<void>;
+    setReplayGuard?(name: string, guard: ReplayGuard | null): void;
+}
+/** What a claimed dispatch turned into — mirror of the ledger's own type. */
+type ScheduleDispatchOutcome = 'succeeded' | 'failed';
+/** One dispatch-claim row, as this trigger reads it back. */
+interface ScheduleDispatchClaim {
+    readonly outcome: ScheduleDispatchOutcome | null;
+    readonly claimedAt: string | null;
+}
+/**
+ * The slice of the automation service this trigger needs for once-per-window
+ * delivery (#14501): the same `sys_flow_dispatch` claim ledger the
+ * time-relative trigger uses for its per-record keys (#10220), plus the
+ * outcome half the #14501 ruling added.
+ *
+ * Typed structurally — like {@link JobServiceSurface} — so this plugin never
+ * learns the ledger's table name and takes no build dependency on
+ * `@objectstack/service-automation`. `settleDispatch` / `readDispatch` are
+ * optional for the same reason `claim` is resolved defensively: an automation
+ * service predating either one resolves to a partial surface, and the trigger
+ * degrades honestly rather than throwing at bind time.
+ */
+interface ScheduleDispatchLedger {
+    claim(key: string): Promise<boolean>;
+    settleDispatch?(key: string, outcome: ScheduleDispatchOutcome): Promise<void>;
+    readDispatch?(key: string): Promise<ScheduleDispatchClaim | null>;
 }
 /** Minimal logger surface (matches core's `ctx.logger`). */
 interface TriggerLogger {
@@ -105,6 +162,26 @@ declare function normalizeSchedule(raw: unknown): JobSchedule | null;
  * The job service is resolved lazily (per `start()`) via the supplied accessor,
  * so we always pick up the job service's *upgraded* adapter (e.g. the durable
  * DbJobAdapter that replaces the bootstrap interval adapter on `kernel:ready`).
+ *
+ * ## Once-per-window delivery (#14501)
+ *
+ * A scheduled flow claims a `(flow, tick-window)` key in the shared
+ * `sys_flow_dispatch` ledger before it launches, and settles that claim with
+ * the run's outcome afterwards — the same ledger the time-relative trigger
+ * claims per `(flow, record, window)` (#10220), with the key shape the
+ * maintainer's A + a2 ruling named. Three doors close at once:
+ *
+ *  - a second tick inside one window finds the claim and does nothing;
+ *  - a restart inside a window is that same case, because the key is a pure
+ *    function of the schedule descriptor and the clock, not of process state;
+ *  - an operator `replay()` of a window that was DELIVERED is refused with an
+ *    ADR-0112 `RESOURCE_CONFLICT` / 409 envelope, via the
+ *    {@link ReplayGuard} this trigger registers on the job service.
+ *
+ * What did NOT change is the error isolation: a throwing flow is still caught
+ * and swallowed so the ticker survives. It stopped being SILENT — the throw
+ * settles the window's claim `failed`, and a plain `replay()` re-runs a failed
+ * window — but the ticker's protection is unchanged and must stay that way.
  */
 declare class ScheduleTrigger implements FlowTrigger {
     readonly type = "schedule";
@@ -112,8 +189,77 @@ declare class ScheduleTrigger implements FlowTrigger {
     private readonly logger;
     /** flowName → job name registered for it, so stop() can cancel it. */
     private readonly bound;
-    constructor(getJobService: () => JobServiceSurface | null, logger: TriggerLogger);
+    /** Dispatch-claim ledger (#14501), resolved lazily per fire. */
+    private readonly getLedger;
+    /** Injectable clock so window math is deterministic under test. */
+    private readonly now;
+    /**
+     * flowName → the ONE dispatch key a {@link ReplayGuard} has authorised for
+     * re-dispatch (#14501). A replay of a window whose claim is absent or
+     * failed must actually re-run it — but the handler's own claim gate would
+     * see the existing row and no-op, so the guard leaves a one-shot pass here
+     * and the handler consumes it. In-process by construction and correctly
+     * so: the pass is written and read inside a single `replay()` call chain.
+     *
+     * Keyed by FLOW rather than accumulated in a set, so a pass a job service
+     * asked for and then abandoned is overwritten by the next one instead of
+     * outliving its window — at most one outstanding pass per bound flow, and
+     * `stop()` takes it with the binding.
+     *
+     * ⚠️ Residue is therefore bounded but not zero: an abandoned pass survives
+     * until this flow's next guard call replaces it, or `stop()` drops it. A
+     * later fire does NOT clear it — the handler deletes the entry only when
+     * the pass MATCHES the window it just computed — so an abandoned pass
+     * outlives every fire in every other window. It stays inert through all of
+     * them for the same reason: a pass naming a window that has passed can
+     * never match again. Its blast radius is one fire of one flow inside the
+     * window the pass names, and only if that window is still current — a fire
+     * that would have been a no-op runs instead.
+     */
+    private readonly replayPasses;
+    /** Whether the in-process-only dedup degradation has been said (once). */
+    private claimDegradationWarned;
+    /** Whether the "no replay guard could be installed" degradation has been said (once). */
+    private replayGuardDegradationWarned;
+    constructor(getJobService: () => JobServiceSurface | null, logger: TriggerLogger, getLedger?: () => ScheduleDispatchLedger | null, now?: () => Date);
     start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void;
+    /**
+     * Install the `replay()` pre-flight for this job (#14501), when the job
+     * service has somewhere to put one.
+     *
+     * Degradation contract, declared once: a job service without
+     * `setReplayGuard` (the bootstrap `IntervalJobAdapter`, any adapter
+     * predating #14501) keeps every other guarantee here — a second tick in a
+     * window is still a no-op, a throw is still recorded failed — but an
+     * operator replay of a DELIVERED window can no longer be refused loudly.
+     * It hits the handler's claim gate and returns having done nothing, which
+     * is the silent no-op the ruling exists to prevent, so it is said out loud
+     * here instead.
+     *
+     * ⚠ Said only when a ledger is actually attached. With no ledger nothing is
+     * ever RECORDED as delivered, so there is no refusal to lose and the line
+     * would be a false alarm — that deployment's real degradation is the
+     * "delivery is NOT deduplicated" warning {@link claimDispatch} already
+     * emits, and stacking a second, vacuous warning on top of it buries the
+     * one that matters.
+     */
+    private installReplayGuard;
+    /**
+     * Claim one `(flow, tick-window)` dispatch key (#14501): `true` = launch,
+     * `false` = this window was already dispatched (an earlier tick this
+     * process, or a previous process lifetime).
+     *
+     * Degradation contract, deliberately identical to the time-relative
+     * trigger's: a ledger call that THROWS dispatches anyway (availability
+     * over strict-once — a broken ledger must never silently swallow a
+     * digest), and a missing ledger is warned once because the once-per-window
+     * guarantee then no longer survives a kernel rebuild.
+     */
+    private claimDispatch;
+    /** Record what a dispatch turned into. Best-effort: never fails the run. */
+    private settleDispatch;
+    /** Read one dispatch claim. A ledger that cannot answer reports `null`. */
+    private readDispatch;
     stop(flowName: string): void;
 }
 
@@ -304,4 +450,4 @@ declare class TimeRelativeTrigger implements FlowTrigger {
     stop(flowName: string): void;
 }
 
-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 };
+export { type DateWindow, type FlowDispatchClaimSurface, type FlowTrigger, type FlowTriggerBinding, type JobServiceSurface, type ReplayGuard, type ReplayGuardDecision, type ScheduleDispatchClaim, type ScheduleDispatchLedger, type ScheduleDispatchOutcome, ScheduleTrigger, ScheduleTriggerPlugin, type TimeRelativeDataEngine, TimeRelativeTrigger, TimeRelativeTriggerPlugin, type TriggerLogger, type WindowClaimScope, buildWindowWhere, computeDateWindows, computeWindowClaimScopes, normalizeSchedule };