feat(spec): IJobService.replay gains an optional options argument carrying force: true (#14766) (#15377)

The contract half of the #14501 A+a2 ruling: `replay?(name, data?, options?: JobReplayOptions)`.
The TSDoc declares the three outcomes by claim state (absent / failed re-run the window;
succeeded is refused with an ADR-0112 envelope — RESOURCE_CONFLICT / 409 — naming the window
and the claim; `{ force: true }` sends anyway). Behaviour stays on #14501.

- exported `JobReplayOptions { force?: boolean }` (options object, the `schedule` convention)
- type-level pin block in job-service.test.ts (additivity, identity, source-reading)
- regenerated api-surface/contracts.json and export-origins/contracts.json
- changeset: @objectstack/spec minor


Claude-Session: https://claude.ai/code/session_01H2oQebDDxYKfWZusyd8GXk

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: os-justin

.changeset/job-service-replay-force.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `IJobService.replay` gains an optional third argument, `options?: JobReplayOptions`, carrying `force: true` (#14766 — the contract half of the #14501 A+a2 ruling)
+
+Additive: the argument is optional, an existing two-argument `replay(name, data?)` implementation keeps compiling and behaving as before, and omitting it is the pre-#14766 call exactly. `JobReplayOptions` is exported from `@objectstack/spec` (`contracts`), with one member, `force?: boolean`.
+
+**What the contract now declares** (`packages/spec/src/contracts/job-service.ts`, the `replay` TSDoc), for a scheduled (cron) flow whose tick window takes a `(flow, tick-window)` dispatch claim in `sys_flow_dispatch`:
+
+- `replay(name, data)` on a window whose claim is **absent or failed** re-runs the window — unchanged behaviour, and every job that never takes a claim is this row;
+- `replay(name, data)` on a window whose claim **succeeded** is **refused loudly**: the promise rejects with an ADR-0112 envelope — `code: 'RESOURCE_CONFLICT'` (the standard-catalog member HTTP 409 derives; no new extension code) and `status: 409` — whose message names the window asked for and the claim that refused it. Never a silent no-op;
+- `replay(name, data, { force: true })` sends anyway; the duplicate is the operator's, taken knowingly.
+
+**Declared here, enforced by #14501.** This release changes the contract text and the signature only. The refusal semantics are implemented by the services half (#14501: the `(flow, tick-window)` claim through `sys_flow_dispatch`, and `DbJobAdapter.replay` reading it); until that lands, shipped adapters still accept the third argument and ignore it, re-running the window as before. A third-party `IJobService` implementation that already declares `replay` needs no change to keep compiling; one that wants the once-only guarantee implements the table above.

packages/spec/api-surface/contracts.json

@@ -170,6 +170,7 @@
     "IntrospectedTable (interface)",
     "JobExecution (type)",
     "JobHandler (type)",
+    "JobReplayOptions (interface)",
     "JobRetryPolicy (interface)",
     "JobRunOutcome (interface)",
     "JobSchedule (interface)",

packages/spec/export-origins/contracts.json

@@ -170,6 +170,7 @@
     "IntrospectedTable": "src/contracts/schema-diff-service.ts#IntrospectedTable (interface)",
     "JobExecution": "src/system/job.zod.ts#JobExecution (type)",
     "JobHandler": "src/contracts/job-service.ts#JobHandler (type)",
+    "JobReplayOptions": "src/contracts/job-service.ts#JobReplayOptions (interface)",
     "JobRetryPolicy": "src/contracts/job-service.ts#JobRetryPolicy (interface)",
     "JobRunOutcome": "src/contracts/job-service.ts#JobRunOutcome (interface)",
     "JobSchedule": "src/contracts/job-service.ts#JobSchedule (interface)",

packages/spec/src/contracts/job-service.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from 'vitest';
-import type { IJobService, JobHandler, JobRunOutcome, JobExecution } from './job-service';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import type { IJobService, JobHandler, JobRunOutcome, JobExecution, JobReplayOptions } from './job-service';
 
 describe('Job Service Contract', () => {
   it('should allow a minimal IJobService implementation with required methods', () => {
@@ -244,3 +246,103 @@ describe('[#6617] JobHandler degraded-outcome channel', () => {
     expect(thrownAttempts).toBe(4); // ← a throw still retries, unchanged
   });
 });
+
+/**
+ * [#14766] `IJobService.replay` gains an optional third argument carrying
+ * `force: true` — the contract half of the maintainer's A + a2 ruling on
+ * #14501 (whose behaviour half lands in `DbJobAdapter.replay`).
+ *
+ * COMPILE-TIME pins first (`tsconfig.test.json` type-checks this file under
+ * `check:test-typecheck`, so an assignability pin here is a real check), and
+ * one source-reading pin for the prose the services implementer codes
+ * against: the refusal is declared on the contract, and prose is unassertable
+ * except by reading it. Reverse verification for the block: narrow the
+ * signature back to `(name, data?)` — (b), (c) and the identity pin go red,
+ * (a) stays green. That asymmetry IS additivity.
+ */
+describe('[#14766] IJobService.replay force option — contract half of the #14501 A+a2 ruling', () => {
+  type Eq<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+  type ReplayParams = Parameters<NonNullable<IJobService['replay']>>;
+
+  /**
+   * The replay signature EXACTLY as it stood before #14766, pinned standalone
+   * so the additivity claim is falsifiable: if the third parameter ever stops
+   * being optional, this implementation stops being assignable.
+   */
+  type PreIssue14766Replay = (name: string, data?: unknown) => Promise<void>;
+
+  const base = {
+    schedule: async () => {},
+    cancel: async () => {},
+    trigger: async () => {},
+  } satisfies Pick<IJobService, 'schedule' | 'cancel' | 'trigger'>;
+
+  it('(a) an existing two-argument replay implementation is unchanged — additivity, implementer side', async () => {
+    // `DbJobAdapter.replay(name, data?)` as it stands on main: it declares no
+    // third parameter, and must keep compiling untouched (#14501 widens it).
+    const legacy: PreIssue14766Replay = async (_name, _data) => {};
+    const service: IJobService = { ...base, replay: legacy };
+
+    await expect(service.replay!('digest')).resolves.toBeUndefined();
+    await expect(service.replay!('digest', { since: 'yesterday' })).resolves.toBeUndefined();
+  });
+
+  it('(b) the options type is exported, and a call site passes { force: true } through it', async () => {
+    const seen: Array<JobReplayOptions | undefined> = [];
+    const service: IJobService = {
+      ...base,
+      replay: async (_name, _data, options) => {
+        seen.push(options);
+      },
+    };
+
+    // THE pin that goes red when the third parameter is removed.
+    const force: JobReplayOptions = { force: true };
+    await service.replay!('digest', undefined, force);
+    await service.replay!('digest', undefined, { force: false });
+    await service.replay!('digest');
+
+    expect(seen).toEqual([{ force: true }, { force: false }, undefined]);
+  });
+
+  it('(c) the third parameter IS JobReplayOptions, optional, and force is its only member', () => {
+    // Identity, not assignability: a widening or a narrowing on either side
+    // turns this alias red under check:test-typecheck.
+    const identity: Eq<ReplayParams[2], JobReplayOptions | undefined> = true;
+    expect(identity).toBe(true);
+
+    const bare: JobReplayOptions = {};
+    expect(bare.force).toBeUndefined();
+
+    // @ts-expect-error force is a boolean — a truthy string is not the door.
+    const stringly: JobReplayOptions = { force: 'yes' };
+    expect(stringly.force).toBe('yes');
+
+    // @ts-expect-error force is the ONLY knob; a second one is a spec decision
+    // (a new key on this interface), not a free-text field.
+    const extra: JobReplayOptions = { force: true, skipClaim: true };
+    expect(extra.force).toBe(true);
+  });
+
+  it('(d) the contract text declares the refusal the services half codes against', () => {
+    const source = readFileSync(fileURLToPath(new URL('./job-service.ts', import.meta.url)), 'utf8');
+    const start = source.indexOf('replay?(name: string, data?: unknown, options?: JobReplayOptions)');
+    expect(start).toBeGreaterThan(0);
+    // The doc block immediately above the declaration.
+    const docBlock = source.slice(source.lastIndexOf('/**', start), start);
+
+    // The three outcomes, by the claim state that selects them…
+    expect(docBlock).toContain('(flow, tick-window)');
+    expect(docBlock).toContain('**absent**');
+    expect(docBlock).toContain('**failed**');
+    expect(docBlock).toContain('**succeeded**');
+    // …the refusal as an ADR-0112 envelope on code AND status, naming what it refuses…
+    expect(docBlock).toContain('ADR-0112');
+    expect(docBlock).toContain("code: 'RESOURCE_CONFLICT'");
+    expect(docBlock).toContain('status: 409');
+    expect(docBlock).toContain('**the window**');
+    expect(docBlock).toContain('**the claim**');
+    // …and the one door past it.
+    expect(docBlock).toContain('options.force: true');
+  });
+});

packages/spec/src/contracts/job-service.ts

@@ -158,6 +158,32 @@ export interface JobScheduleOptions {
     timeout?: number;
 }
 
+/**
+ * The optional third argument of {@link IJobService.replay} (#14766 — the
+ * contract half of the maintainer's A + a2 ruling on #14501).
+ *
+ * An options object rather than a bare positional boolean, by the convention
+ * this interface already follows for `schedule(…, options?: JobScheduleOptions)`:
+ * a named, exported options type reads at the call site —
+ * `replay(name, data, { force: true })` says what it does, `replay(name, data,
+ * true)` does not — and a later knob is a second key here, never a fourth
+ * positional. Omitting the argument is the pre-#14766 call exactly.
+ */
+export interface JobReplayOptions {
+    /**
+     * Re-send a scheduled flow's tick window even though that window's
+     * `(flow, tick-window)` dispatch claim has already **succeeded**.
+     *
+     * Absent or `false`, a replay of a delivered window is refused with the
+     * ADR-0112 envelope {@link IJobService.replay} declares. `true` is the
+     * explicit operator door the ruling kept open (option a2): the operator is
+     * stating that the window is known to have been delivered and is to be
+     * delivered again, and takes the duplicate knowingly. It never touches a
+     * window whose claim is absent or failed — those re-run either way.
+     */
+    force?: boolean;
+}
+
 export interface IJobService {
     /**
      * Schedule a recurring or one-time job
@@ -202,8 +228,50 @@ export interface IJobService {
      * `sys_audit_log`, with its own opt-in, writer and retention. Recording
      * anything durable depends on an adapter that persists run history at all
      * (e.g. `DbJobAdapter`'s `recordRuns` option).
+     *
+     * **Once-only delivery on the scheduled path** (#14766, the contract half
+     * of the maintainer's A + a2 ruling on #14501; the behaviour half is
+     * #14501 and lands in `DbJobAdapter.replay`). A scheduled (cron) flow
+     * takes a dispatch claim in the `sys_flow_dispatch` ledger keyed
+     * `(flow, tick-window)` — the same ledger a `time_relative` flow claims per
+     * `(flow, window, record)` (#10220). A replay of a scheduled flow reads
+     * that window's claim, and the contract admits exactly three outcomes:
+     *
+     * | The `(flow, tick-window)` claim is… | `replay(name, data)` | `replay(name, data, { force: true })` |
+     * |:---|:---|:---|
+     * | **absent** — the window was never claimed | re-runs the window (unchanged behaviour) | re-runs the window |
+     * | **failed** — claimed, and the dispatch did not succeed | re-runs the window (unchanged behaviour) | re-runs the window |
+     * | **succeeded** — the window was delivered | **refused**, loudly — see below | re-runs the window: sends anyway, the duplicate is the operator's, taken knowingly |
+     *
+     * A job that never takes a claim — every job that is not a scheduled
+     * flow — is the **absent** row: it re-runs, with or without `force`, and
+     * nothing about it changes.
+     *
+     * **The refusal is an ADR-0112 envelope, never a silent no-op.** The
+     * promise **rejects** (it does not resolve having done nothing — the
+     * ruling rejected that shape outright: an operator who pressed replay and
+     * saw nothing happen is the bad experience this clause exists to prevent)
+     * with an error carrying `code: 'RESOURCE_CONFLICT'` — the standard-catalog
+     * member HTTP 409 derives (`HttpStatusErrorCodeMap[409]`, `api/errors.zod.ts`;
+     * no service extension code is registered for this) — and `status: 409`,
+     * and its message names **the window** that was asked for (the flow and
+     * its tick window) and **the claim** that refused it (the
+     * `sys_flow_dispatch` row: when the window was claimed and that the
+     * dispatch succeeded). A consumer asserts the refusal on `code` and
+     * `status`; the message is for the operator reading it.
+     *
+     * `options.force: true` is the only door past the refusal (option a2).
+     * Option a1 (refuse always, no door) and option a3 (send anyway, accept
+     * the duplicate silently) were considered on #14501 and **not** taken.
+     *
+     * @param name - Job name
+     * @param data - Optional data to pass to the handler
+     * @param options - {@link JobReplayOptions}; omitted is the pre-#14766
+     * call and refuses a delivered window
+     * @throws `RESOURCE_CONFLICT` / 409 when the window's claim succeeded and
+     * `options.force` is not `true`
      */
-    replay?(name: string, data?: unknown): Promise<void>;
+    replay?(name: string, data?: unknown, options?: JobReplayOptions): Promise<void>;
 
     /**
      * List executions filtered by status across all jobs (admin/observability).