@memberjunction/integration-engine 6.1.0-edge.2 → 6.1.0-edge.4

package/dist/RetryAfter.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Standard `Retry-After` extraction, so a connector that writes no rate-limit code
+ * still backs off by the amount the vendor actually asked for.
+ *
+ * `BaseIntegrationConnector.ExtractRetryAfterMs` returned `undefined` unconditionally and no
+ * connector in this repo overrode it. The engine's limiter therefore always fell back to its own
+ * multiplicative decrease — correct in direction, but blind to a number the vendor had already
+ * supplied in the response.
+ *
+ * `Retry-After` is defined by RFC 9110 §10.2.3 and is the header a 429 (RFC 6585) and a 503 carry.
+ * Parsing it is not a heuristic and not vendor-specific, which is exactly why it belongs in the
+ * base class rather than in each connector: there is one correct reading of it, and every HTTP
+ * connector benefits from having it read.
+ *
+ * Deliberately NOT a message-text parser. Guessing a duration out of prose ("try again in a bit")
+ * risks inventing a number, and a wrong Retry-After is worse than none — it would freeze the bucket
+ * for a made-up interval. Text-shaped signals stay the connector's job (see PheedLoop, whose vendor
+ * puts its delay in the body rather than a header); this reads the standard header only.
+ */
+/**
+ * Upper bound on an honored `Retry-After`, in milliseconds (5 minutes).
+ *
+ * A vendor occasionally returns an enormous or malformed value — a Unix timestamp mistaken for
+ * delay-seconds, a date years out. Freezing a sync's token bucket for hours on the strength of one
+ * response is a worse failure than backing off by the limiter's own decrease, so anything beyond
+ * this is treated as unusable and the limiter's default applies.
+ */
+export const MAX_HONORED_RETRY_AFTER_MS = 5 * 60_000;
+/**
+ * Reads one header by name from a `Headers` instance, a `Map`, or a plain object, case-insensitively.
+ * Returns undefined when the container is not one of those or the header is absent.
+ */
+function readHeader(container, name) {
+    if (!container || typeof container !== 'object')
+        return undefined;
+    // fetch's Headers (and anything else exposing a case-insensitive get)
+    const getter = container.get;
+    if (typeof getter === 'function') {
+        try {
+            const v = container.get(name);
+            if (typeof v === 'string' && v.length > 0)
+                return v;
+        }
+        catch { /* not a Headers-like after all */ }
+    }
+    // Plain object / axios-style header bag. Node lower-cases response header names, but a hand-built
+    // object may not, so compare case-insensitively rather than trusting the spelling.
+    const target = name.toLowerCase();
+    for (const [k, v] of Object.entries(container)) {
+        if (k.toLowerCase() !== target)
+            continue;
+        // Node can hand back string[] for a repeated header; the first value is the one that counts.
+        const raw = Array.isArray(v) ? v[0] : v;
+        if (typeof raw === 'string' && raw.length > 0)
+            return raw;
+        if (typeof raw === 'number' && Number.isFinite(raw))
+            return String(raw);
+    }
+    return undefined;
+}
+/**
+ * Parses a `Retry-After` value into milliseconds. RFC 9110 permits two forms:
+ *   - delay-seconds: a non-negative integer, e.g. `120`
+ *   - HTTP-date:     e.g. `Wed, 21 Oct 2015 07:28:00 GMT`
+ *
+ * @param value the raw header value
+ * @param nowMs clock reading used to convert an HTTP-date into a delay; injectable for tests
+ * @returns milliseconds to wait, or undefined when the value is unusable
+ */
+export function ParseRetryAfterValue(value, nowMs = Date.now()) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    // delay-seconds. Accept only a bare integer: a decimal or anything with trailing junk is not
+    // what the spec defines, and Number() would happily coerce forms that mean something else.
+    if (/^\d+$/.test(trimmed)) {
+        const ms = Number(trimmed) * 1000;
+        return ms > 0 && ms <= MAX_HONORED_RETRY_AFTER_MS ? ms : undefined;
+    }
+    // HTTP-date. `Date.parse` is extremely permissive — it happily reads '1.5' as a date and
+    // returns a real timestamp — so gate it on the string actually LOOKING like one first.
+    // Every form RFC 9110 permits (IMF-fixdate, obsolete RFC 850, asctime) carries a three-letter
+    // day or month name AND a digit; the junk that reaches here ('1.5', '30s', '1e3', 'soon')
+    // carries at most one of the two. Falling through to a misparsed date would invent a delay,
+    // which is the one outcome worse than having none.
+    if (!/[A-Za-z]{3}/.test(trimmed) || !/\d/.test(trimmed))
+        return undefined;
+    // A date already in the past means "retry now" — no wait, but also not a parse failure, so it
+    // must not fall through to the limiter's default as though nothing was said.
+    const at = Date.parse(trimmed);
+    if (Number.isNaN(at))
+        return undefined;
+    const ms = at - nowMs;
+    if (ms <= 0)
+        return 0;
+    return ms <= MAX_HONORED_RETRY_AFTER_MS ? ms : undefined;
+}
+/**
+ * Extracts a `Retry-After` delay, in milliseconds, from a thrown error or a failed response.
+ *
+ * Walks the shapes HTTP clients actually throw: the error itself carrying `headers`, an axios-style
+ * `error.response.headers`, and one level of `error.cause` (how a wrapper preserves the original).
+ *
+ * @param error the thrown value
+ * @param nowMs clock reading for HTTP-date conversion; injectable for tests
+ * @returns milliseconds to wait, or undefined when no usable header is present
+ */
+export function ExtractRetryAfterFromError(error, nowMs = Date.now()) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const e = error;
+    const candidates = [
+        e.headers,
+        e.response?.headers,
+        e.cause?.headers,
+        e.cause?.response?.headers,
+    ];
+    for (const container of candidates) {
+        const parsed = ParseRetryAfterValue(readHeader(container, 'retry-after'), nowMs);
+        if (parsed !== undefined)
+            return parsed;
+    }
+    return undefined;
+}
+//# sourceMappingURL=RetryAfter.js.map

package/dist/RetryAfter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetryAfter.js","sourceRoot":"","sources":["../src/RetryAfter.ts"],"names":[],"mappings":"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"}

package/dist/RetryRunner.d.ts

@@ -13,15 +13,39 @@ export interface RetryConfig {
 }
 /** Default retry configuration */
 export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Optional hooks that let a caller make the wait between attempts smarter than blind backoff.
+ *
+ * Both exist for rate limiting. Exponential backoff is the right default for a network blip, but it
+ * is the WRONG answer to a 429: the source has usually told us exactly how long to wait, and
+ * retrying sooner is what turns a soft throttle into a hard one.
+ */
+export interface RetryHooks {
+    /**
+     * Derive the wait from the error itself — e.g. a `Retry-After` header. Return `null`/`undefined`
+     * to keep the computed exponential backoff. The larger of the two is NOT taken automatically;
+     * returning a value replaces the backoff, so a caller can honour a source that asks for a
+     * SHORTER wait as well as a longer one.
+     */
+    DelayForError?: (error: unknown, attempt: number, backoffMs: number) => number | null | undefined;
+    /**
+     * Awaited after the delay and before the next attempt — e.g. re-acquiring a rate-limit token, so
+     * a retry passes through the same gate the first attempt did instead of bypassing it.
+     */
+    BeforeRetry?: (attempt: number, error: unknown) => Promise<void> | void;
+}
 /**
  * Executes an operation with retry logic using exponential backoff.
  *
  * @param operation - The async operation to execute
  * @param config - Retry configuration (uses defaults if not provided)
  * @param isRetryable - Predicate to determine if a caught error should trigger a retry
- * @param onRetry - Optional callback invoked before each retry with attempt number, error, and delay
+ * @param onRetry - Optional callback invoked before each retry with attempt number, error, and delay.
+ *                  Runs BEFORE the wait, so it is the right place to report the failure onward (e.g.
+ *                  backing off a shared limiter) rather than after the retries are spent.
+ * @param hooks - Optional {@link RetryHooks} for source-directed delays and pre-attempt gating
  * @returns The result of the operation
  * @throws The last error encountered if all attempts fail
  */
-export declare function WithRetry<T>(operation: () => Promise<T>, config?: RetryConfig, isRetryable?: (error: unknown) => boolean, onRetry?: (attempt: number, error: unknown, delayMs: number) => void): Promise<T>;
+export declare function WithRetry<T>(operation: () => Promise<T>, config?: RetryConfig, isRetryable?: (error: unknown) => boolean, onRetry?: (attempt: number, error: unknown, delayMs: number) => void, hooks?: RetryHooks): Promise<T>;
 //# sourceMappingURL=RetryRunner.d.ts.map

package/dist/RetryRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RetryRunner.d.ts","sourceRoot":"","sources":["../src/RetryRunner.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,kCAAkC;AAClC,eAAO,MAAM,oBAAoB,EAAE,WAKlC,CAAC;AAeF;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC7B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,MAAM,GAAE,WAAkC,EAC1C,WAAW,GAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAoB,EACrD,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GACrE,OAAO,CAAC,CAAC,CAAC,CAyBZ"}
+{"version":3,"file":"RetryRunner.d.ts","sourceRoot":"","sources":["../src/RetryRunner.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,kCAAkC;AAClC,eAAO,MAAM,oBAAoB,EAAE,WAKlC,CAAC;AAeF;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClG;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC7B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,MAAM,GAAE,WAAkC,EAC1C,WAAW,GAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAoB,EACrD,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,EACpE,KAAK,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,CAAC,CAAC,CA+BZ"}

package/dist/RetryRunner.js

@@ -23,11 +23,14 @@ function computeDelay(attempt, config) {
  * @param operation - The async operation to execute
  * @param config - Retry configuration (uses defaults if not provided)
  * @param isRetryable - Predicate to determine if a caught error should trigger a retry
- * @param onRetry - Optional callback invoked before each retry with attempt number, error, and delay
+ * @param onRetry - Optional callback invoked before each retry with attempt number, error, and delay.
+ *                  Runs BEFORE the wait, so it is the right place to report the failure onward (e.g.
+ *                  backing off a shared limiter) rather than after the retries are spent.
+ * @param hooks - Optional {@link RetryHooks} for source-directed delays and pre-attempt gating
  * @returns The result of the operation
  * @throws The last error encountered if all attempts fail
  */
-export async function WithRetry(operation, config = DEFAULT_RETRY_CONFIG, isRetryable = () => true, onRetry) {
+export async function WithRetry(operation, config = DEFAULT_RETRY_CONFIG, isRetryable = () => true, onRetry, hooks) {
     let lastError;
     for (let attempt = 1; attempt <= config.MaxAttempts; attempt++) {
         try {
@@ -39,11 +42,16 @@ export async function WithRetry(operation, config = DEFAULT_RETRY_CONFIG, isRetr
             if (isLastAttempt || !isRetryable(err)) {
                 throw err;
             }
-            const delayMs = computeDelay(attempt, config);
+            const backoffMs = computeDelay(attempt, config);
+            const directed = hooks?.DelayForError?.(err, attempt, backoffMs);
+            const delayMs = typeof directed === 'number' && Number.isFinite(directed) && directed >= 0
+                ? directed
+                : backoffMs;
             if (onRetry) {
                 onRetry(attempt, err, delayMs);
             }
             await sleep(delayMs);
+            await hooks?.BeforeRetry?.(attempt, err);
         }
     }
     // Should not reach here, but TypeScript needs this

package/dist/RetryRunner.js.map

@@ -1 +1 @@
-{"version":3,"file":"RetryRunner.js","sourceRoot":"","sources":["../src/RetryRunner.ts"],"names":[],"mappings":"AAcA,kCAAkC;AAClC,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC7C,WAAW,EAAE,CAAC;IACd,gBAAgB,EAAE,IAAI;IACtB,YAAY,EAAE,KAAK;IACnB,cAAc,EAAE,GAAG;CACtB,CAAC;AAEF;;;;;GAKG;AACH,SAAS,YAAY,CAAC,OAAe,EAAE,MAAmB;IACtD,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;IAC5E,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC9D,OAAO,MAAM,GAAG,MAAM,CAAC;AAC3B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC3B,SAA2B,EAC3B,SAAsB,oBAAoB,EAC1C,cAA2C,GAAG,EAAE,CAAC,IAAI,EACrD,OAAoE;IAEpE,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,MAAM,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QAC7D,IAAI,CAAC;YACD,OAAO,MAAM,SAAS,EAAE,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,SAAS,GAAG,GAAG,CAAC;YAEhB,MAAM,aAAa,GAAG,OAAO,KAAK,MAAM,CAAC,WAAW,CAAC;YACrD,IAAI,aAAa,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;gBACrC,MAAM,GAAG,CAAC;YACd,CAAC;YAED,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC9C,IAAI,OAAO,EAAE,CAAC;gBACV,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;YACnC,CAAC;YAED,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;IACL,CAAC;IAED,mDAAmD;IACnD,MAAM,SAAS,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,SAAS,KAAK,CAAC,EAAU;IACrB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"RetryRunner.js","sourceRoot":"","sources":["../src/RetryRunner.ts"],"names":[],"mappings":"AAcA,kCAAkC;AAClC,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC7C,WAAW,EAAE,CAAC;IACd,gBAAgB,EAAE,IAAI;IACtB,YAAY,EAAE,KAAK;IACnB,cAAc,EAAE,GAAG;CACtB,CAAC;AAEF;;;;;GAKG;AACH,SAAS,YAAY,CAAC,OAAe,EAAE,MAAmB;IACtD,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;IAC5E,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC9D,OAAO,MAAM,GAAG,MAAM,CAAC;AAC3B,CAAC;AAwBD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC3B,SAA2B,EAC3B,SAAsB,oBAAoB,EAC1C,cAA2C,GAAG,EAAE,CAAC,IAAI,EACrD,OAAoE,EACpE,KAAkB;IAElB,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,MAAM,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QAC7D,IAAI,CAAC;YACD,OAAO,MAAM,SAAS,EAAE,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,SAAS,GAAG,GAAG,CAAC;YAEhB,MAAM,aAAa,GAAG,OAAO,KAAK,MAAM,CAAC,WAAW,CAAC;YACrD,IAAI,aAAa,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;gBACrC,MAAM,GAAG,CAAC;YACd,CAAC;YAED,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAChD,MAAM,QAAQ,GAAG,KAAK,EAAE,aAAa,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;YACjE,MAAM,OAAO,GAAG,OAAO,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC;gBACtF,CAAC,CAAC,QAAQ;gBACV,CAAC,CAAC,SAAS,CAAC;YAEhB,IAAI,OAAO,EAAE,CAAC;gBACV,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;YACnC,CAAC;YAED,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;YACrB,MAAM,KAAK,EAAE,WAAW,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC7C,CAAC;IACL,CAAC;IAED,mDAAmD;IACnD,MAAM,SAAS,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,SAAS,KAAK,CAAC,EAAU;IACrB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/RunOwnershipService.d.ts

@@ -0,0 +1,177 @@
+import type { DatabaseProviderBase, UserInfo } from '@memberjunction/core';
+import type { MJCompanyIntegrationRunEntity } from '@memberjunction/core-entities';
+/**
+ * Thrown at a batch boundary when this process discovers it no longer owns the
+ * run row (lease reclaimed by a stale-sweep or another worker bumped the fence).
+ * The sync loop MUST let this propagate — per-record error handling must never
+ * swallow it, because continuing to write after ownership loss is exactly the
+ * split-brain hazard the fence exists to prevent.
+ */
+/**
+ * The states a run can be released INTO — the terminal subset of the entity's Status value list.
+ * Derived with `Extract` rather than hand-written so it stays pinned to the CHECK-constraint union
+ * CodeGen generates: if one of these values were ever removed from the column, this type narrows and
+ * every call site fails to compile, instead of silently passing a status the constraint rejects at
+ * runtime. 'In Progress' / 'Pending' / 'Queued' are deliberately excluded — they are not terminal.
+ */
+export type TerminalRunStatus = Extract<MJCompanyIntegrationRunEntity['Status'], 'Success' | 'Failed' | 'Cancelled'>;
+export declare class RunOwnershipLostError extends Error {
+    readonly RunID: string;
+    constructor(runID: string, detail: string);
+}
+/** Result of a lease renewal attempt. */
+export interface RenewResult {
+    /** True when the DB confirmed our token+fence still own the row and extended the lease. */
+    Renewed: boolean;
+    /** True when a cooperative cancel has been requested on the run row (only meaningful when Renewed). */
+    CancelRequested: boolean;
+}
+/** Result of a batch-boundary ownership check. */
+export interface BoundaryCheckResult {
+    /** True when the row's OwnerToken + FenceToken still match ours. */
+    Owned: boolean;
+    /** True when CancelRequestedAt is set on the row. */
+    CancelRequested: boolean;
+}
+/** Options for the background heartbeat started via {@link RunOwnershipService.StartHeartbeat}. */
+export interface HeartbeatOptions {
+    /**
+     * Called (once) when a renewal discovers ownership has been lost. The engine
+     * uses this to abort the in-flight sync locally; writes are additionally
+     * fenced at every batch boundary, so this is fast-fail, not the safety net.
+     */
+    onLost?: () => void;
+    /** Called (once per request) when a renewal observes CancelRequestedAt set. */
+    onCancelRequested?: () => void;
+    /** Supplies the latest progress JSON to piggyback on each renewal write. */
+    progressSupplier?: () => string | null;
+}
+/**
+ * Per-run ownership manager for durable CompanyIntegrationRun execution
+ * (GH tasks.md PR 1). One instance is created per sync run and owns:
+ *
+ * - **Claim**: a single atomic UPDATE...WHERE (unowned OR lease expired) via
+ *   spClaimCompanyIntegrationRun — never select-then-update. Claiming bumps
+ *   FenceToken, invalidating any prior holder's writes.
+ * - **Renew**: timer-driven lease extension (interval ≈ lease/3) via
+ *   spRenewCompanyIntegrationRunLease, token+fence-checked. The renewal result
+ *   doubles as the cross-process cancel signal (returns CancelRequestedAt).
+ * - **Boundary fence**: {@link CheckBoundary} — a cheap SELECT the sync loop
+ *   calls before every batch's writes. Ownership lost ⇒ the loop throws
+ *   {@link RunOwnershipLostError} and writes nothing further.
+ * - **Release**: terminal status write + owner clear, token-checked so a stale
+ *   holder's release no-ops.
+ *
+ * All sproc calls use the dialect-portable positional-parameter convention
+ * (same pattern as ScheduledJobEngine's lock sprocs): SQL Server binds the
+ * sproc's named params to positional `@pN` placeholders via EXEC; PostgreSQL
+ * calls the plpgsql port via `SELECT * FROM fn($1,...)`. The SAME value array
+ * serves both.
+ */
+export declare class RunOwnershipService {
+    /** Default lease when the caller supplies no MaxRuntimeMinutes. */
+    static readonly DEFAULT_LEASE_MINUTES = 10;
+    private readonly provider;
+    private readonly contextUser;
+    private readonly runID;
+    private readonly ownerToken;
+    private readonly leaseMinutes;
+    private fenceToken;
+    private lastKnownLeaseExpiresAt;
+    private heartbeatTimer;
+    private lostNotified;
+    private cancelNotified;
+    private renewInFlight;
+    /**
+     * @param provider the run's OWN provider connection (per-run, never a shared
+     *        engine-level provider — see the per-run-connection requirement).
+     * @param runID CompanyIntegrationRun.ID this service governs.
+     * @param leaseMinutes lease length; callers pass
+     *        max(DEFAULT_LEASE_MINUTES, options.MaxRuntimeMinutes ?? 0) so a
+     *        long-batch override only ever EXTENDS protection.
+     */
+    constructor(provider: DatabaseProviderBase, runID: string, leaseMinutes?: number, contextUser?: UserInfo);
+    /** The CompanyIntegrationRun ID this service governs. */
+    get RunID(): string;
+    /** The opaque owner token minted for this execution. */
+    get OwnerToken(): string;
+    /** The fence token returned by the successful claim (null before claim). */
+    get FenceToken(): number | null;
+    /** Last lease expiry the DB confirmed for us (null before claim). */
+    get LeaseExpiresAt(): Date | null;
+    /** Lease length in minutes this service renews with. */
+    get LeaseMinutes(): number;
+    /**
+     * Atomically claim the run row. Returns true iff WE now own it (the sproc's
+     * single UPDATE succeeded because the row was unowned or its lease had
+     * expired). On success the DB-assigned FenceToken (bumped by the claim) and
+     * lease expiry are cached for renewals and boundary checks.
+     */
+    Claim(): Promise<boolean>;
+    /**
+     * Renew the lease (token+fence-checked). Zero rows back ⇒ ownership lost.
+     * Optionally piggybacks a progress snapshot onto the same write, and always
+     * surfaces the row's CancelRequestedAt so the heartbeat doubles as the
+     * cross-process cancel poll.
+     */
+    Renew(progressJSON?: string | null): Promise<RenewResult>;
+    /**
+     * Batch-boundary fence: a cheap SELECT of the ownership columns. The sync
+     * loop calls this BEFORE each batch's writes; if we no longer own the row,
+     * the caller must throw {@link RunOwnershipLostError} and stop writing.
+     * Deliberately a plain read (no lease extension) — renewal belongs to the
+     * heartbeat timer, and a boundary check must stay cheap enough to run
+     * every batch.
+     */
+    CheckBoundary(): Promise<BoundaryCheckResult>;
+    /**
+     * Terminal release: set the final status, clear OwnerToken/LeaseExpiresAt,
+     * stamp EndedAt if unset. Token- AND fence-checked — a stale holder (lease
+     * reclaimed) releasing late is a harmless no-op (returns false).
+     *
+     * The fence is sent for the same reason Renew() sends it: the owner token proves
+     * only that *some* context using this token owns the row, not that THIS context
+     * still does. Each instance mints its own token and claims once, so the two are
+     * equivalent today — but Claim() is re-callable and overwrites the fence, so
+     * passing it keeps the guarantee in the procedure rather than in call-site
+     * discipline.
+     */
+    Release(finalStatus: TerminalRunStatus): Promise<boolean>;
+    /**
+     * Start the background renewal timer at interval ≈ lease/3 (so a renewal
+     * must fail ~3 consecutive times before the lease can lapse). The timer
+     * body is best-effort and never throws; renewal failures surface through
+     * opts.onLost exactly once. Idempotent — restarting replaces the timer.
+     */
+    StartHeartbeat(opts?: HeartbeatOptions): void;
+    /** Stop the renewal timer (idempotent). */
+    StopHeartbeat(): void;
+    /**
+     * Sync the entity's in-memory ownership columns to the service's last-known
+     * authoritative values before ANY full-row `run.Save()`. The generated
+     * spUpdate writes every column from the entity's in-memory state, so a
+     * terminal Save without this sync would clobber the DB's live
+     * FenceToken/OwnerToken/LeaseExpiresAt with the stale values the entity was
+     * loaded with (typically pre-claim). Call this immediately before each
+     * Save on the run row; Release() then clears ownership atomically.
+     */
+    SyncEntityOwnershipFields(run: MJCompanyIntegrationRunEntity): void;
+    private lastProgressWriteMs;
+    /**
+     * Persist a progress snapshot to the run row's ProgressJSON (PR 1 item 4 —
+     * progress lives in the database; readers query the row). Ownership-guarded
+     * (WHERE OwnerToken AND FenceToken) so a reclaimed run can never overwrite the
+     * new owner's progress. Throttled internally (default once per 5s) so progress
+     * never becomes its own hot path; best-effort — a progress write failure must
+     * never fault the sync.
+     */
+    WriteProgress(progressJSON: string, minIntervalMs?: number): Promise<void>;
+    /** One heartbeat tick: renew, then fan out lost/cancel notifications once each. */
+    private heartbeatOnce;
+    /**
+     * Dialect-portable sproc call, preserving the MJ positional-parameter-array
+     * convention (same helper shape as ScheduledJobEngine.buildLockSprocCall).
+     */
+    private buildSprocCall;
+}
+//# sourceMappingURL=RunOwnershipService.d.ts.map

package/dist/RunOwnershipService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunOwnershipService.d.ts","sourceRoot":"","sources":["../src/RunOwnershipService.ts"],"names":[],"mappings":"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"}