reqon-dsl 0.2.0 → 0.4.0

package/dist/interpreter/http.js

@@ -1,13 +1,36 @@
 import { parseRateLimitHeaders } from '../auth/rate-limiter.js';
 import { CircuitBreakerError } from '../auth/circuit-breaker.js';
 import { sleep } from '../utils/async.js';
-/** Default retry configuration values */
-const DEFAULT_RETRY = {
-    MAX_ATTEMPTS: 3,
-    INITIAL_DELAY_MS: 1000,
-    MAX_DELAY_MS: 30000,
-    BACKOFF: 'exponential',
-};
+import { HTTP_RETRY_DEFAULTS } from '../config/index.js';
+import { FetchError } from '../errors/index.js';
+/**
+ * Parse a `Retry-After` header into a delay in ms, clamped to `maxDelayMs`.
+ * The header may be delta-seconds (`120`) or an HTTP-date; a date in the past or
+ * an unparseable value yields 0 and `undefined` respectively. Clamping stops a
+ * hostile/broken server from pinning the client for hours, and the date branch
+ * stops `parseInt` from turning a date into `NaN` → `sleep(NaN)` → a tight loop.
+ */
+export function parseRetryAfterMs(value, maxDelayMs) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    const seconds = Number(trimmed);
+    let ms;
+    if (trimmed !== '' && Number.isFinite(seconds)) {
+        ms = seconds * 1000;
+    }
+    else {
+        const when = Date.parse(trimmed);
+        if (Number.isNaN(when))
+            return undefined;
+        ms = when - Date.now();
+    }
+    return Math.min(Math.max(ms, 0), maxDelayMs);
+}
+/** Maximum buffered response body size (10 MiB) before the request is rejected. */
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+/** HTTP methods that are safe to retry automatically (idempotent per RFC 7231). */
+const IDEMPOTENT_METHODS = new Set(['GET', 'PUT', 'DELETE']);
 export class HttpClient {
     config;
     constructor(config) {
@@ -15,17 +38,29 @@ export class HttpClient {
     }
     async request(req, retry) {
         const url = this.buildUrl(req.path, req.query);
-        const headers = await this.buildHeaders(req.headers);
+        const requestHeaders = { ...req.headers };
+        if (req.idempotencyKey) {
+            requestHeaders['Idempotency-Key'] = req.idempotencyKey;
+        }
+        const headers = await this.buildHeaders(requestHeaders);
         const fetchOptions = {
             method: req.method,
             headers,
             body: req.body ? JSON.stringify(req.body) : undefined,
         };
-        const maxAttempts = retry?.maxAttempts ?? DEFAULT_RETRY.MAX_ATTEMPTS;
-        const backoff = retry?.backoff ?? DEFAULT_RETRY.BACKOFF;
-        const initialDelay = retry?.initialDelay ?? DEFAULT_RETRY.INITIAL_DELAY_MS;
-        const maxDelay = retry?.maxDelay ?? DEFAULT_RETRY.MAX_DELAY_MS;
+        // Auto-retry only idempotent verbs, or any verb carrying an idempotency key.
+        // A blind retry of POST/PATCH can re-send a write the server already
+        // committed (timeout / dropped socket after commit), duplicating data.
+        const retriable = IDEMPOTENT_METHODS.has(req.method) || Boolean(req.idempotencyKey);
+        const maxAttempts = retry?.maxAttempts ?? HTTP_RETRY_DEFAULTS.MAX_ATTEMPTS;
+        const backoff = retry?.backoff ?? HTTP_RETRY_DEFAULTS.BACKOFF;
+        const initialDelay = retry?.initialDelay ?? HTTP_RETRY_DEFAULTS.INITIAL_DELAY_MS;
+        const maxDelay = retry?.maxDelay ?? HTTP_RETRY_DEFAULTS.MAX_DELAY_MS;
+        const timeout = retry?.timeout ?? this.config.timeout ?? HTTP_RETRY_DEFAULTS.TIMEOUT_MS;
         let lastError = null;
+        // Refresh the token at most once per request to avoid burning a fresh
+        // rotating refresh token on every 401 retry attempt.
+        let hasRefreshed = false;
         // Check circuit breaker before attempting requests
         if (this.config.circuitBreaker && this.config.sourceName) {
             // This will throw CircuitBreakerError if circuit is open
@@ -37,14 +72,16 @@ export class HttpClient {
                 if (attempt > 1 && this.config.circuitBreaker && this.config.sourceName) {
                     if (!this.config.circuitBreaker.canProceed(this.config.sourceName, req.path)) {
                         // Circuit opened during retries, fail fast
-                        throw new CircuitBreakerError(this.config.sourceName, req.path, this.config.circuitBreaker.getStatus(this.config.sourceName, req.path).nextAttemptTime?.getTime() ?? 0 - Date.now());
+                        throw new CircuitBreakerError(this.config.sourceName, req.path, this.config.circuitBreaker
+                            .getStatus(this.config.sourceName, req.path)
+                            .nextAttemptTime?.getTime() ?? 0 - Date.now());
                     }
                 }
                 // Wait for rate limit capacity if we have a rate limiter
                 if (this.config.rateLimiter && this.config.sourceName) {
                     await this.config.rateLimiter.waitForCapacity(this.config.sourceName, req.path);
                 }
-                const response = await fetch(url, fetchOptions);
+                const response = await this.fetchWithTimeout(url, fetchOptions, timeout, req.method);
                 // Extract and record rate limit info from response headers
                 const responseHeaders = {};
                 response.headers.forEach((value, key) => {
@@ -54,17 +91,19 @@ export class HttpClient {
                     const rateLimitInfo = parseRateLimitHeaders(responseHeaders);
                     // Add retry-after from 429 responses
                     if (response.status === 429) {
-                        const retryAfter = response.headers.get('Retry-After');
-                        if (retryAfter) {
-                            rateLimitInfo.retryAfter = parseInt(retryAfter, 10);
+                        const ms = parseRetryAfterMs(response.headers.get('Retry-After'), maxDelay);
+                        if (ms !== undefined) {
+                            rateLimitInfo.retryAfter = Math.ceil(ms / 1000);
                         }
                     }
                     this.config.rateLimiter.recordResponse(this.config.sourceName, rateLimitInfo, req.path);
                 }
-                // Handle rate limiting
-                if (response.status === 429) {
-                    const retryAfter = response.headers.get('Retry-After');
-                    const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : this.calculateDelay(attempt, backoff, initialDelay, maxDelay);
+                // Handle rate limiting: retry only while attempts remain. A 429 on the
+                // final attempt falls through to the >=400 handler below, which throws a
+                // FetchError carrying status 429 — not the generic "all retries" error.
+                if (response.status === 429 && retriable && attempt < maxAttempts) {
+                    const delay = parseRetryAfterMs(response.headers.get('Retry-After'), maxDelay) ??
+                        this.calculateDelay(attempt, backoff, initialDelay, maxDelay);
                     await sleep(delay);
                     continue;
                 }
@@ -74,21 +113,35 @@ export class HttpClient {
                     if (this.config.circuitBreaker && this.config.sourceName) {
                         this.config.circuitBreaker.recordFailure(this.config.sourceName, req.path, response.status);
                     }
-                    if (attempt < maxAttempts) {
+                    if (retriable && attempt < maxAttempts) {
                         const delay = this.calculateDelay(attempt, backoff, initialDelay, maxDelay);
                         await sleep(delay);
                         continue;
                     }
+                    // Non-idempotent without an idempotency key: do not re-send a write
+                    // that the server may have already committed. Return the 5xx instead.
                 }
-                // Handle 401 - try token refresh
-                if (response.status === 401 && this.config.auth?.refreshToken && attempt < maxAttempts) {
+                // Handle 401 - try token refresh (at most once per request)
+                if (response.status === 401 &&
+                    this.config.auth?.refreshToken &&
+                    !hasRefreshed &&
+                    attempt < maxAttempts) {
+                    hasRefreshed = true;
                     await this.config.auth.refreshToken();
-                    // Rebuild headers with new token
-                    const newHeaders = await this.buildHeaders(req.headers);
+                    // Rebuild headers with new token (preserving the idempotency key)
+                    const newHeaders = await this.buildHeaders(requestHeaders);
                     fetchOptions.headers = newHeaders;
                     continue;
                 }
-                const data = await response.json();
+                // Any remaining non-2xx/3xx response is an error: a 4xx (other than the
+                // 429/401-refresh cases handled above) or a 5xx that exhausted retries.
+                // Returning it as `data` would let map/store persist an API error body.
+                if (response.status >= 400) {
+                    const snippet = await this.safeReadSnippet(response);
+                    throw new FetchError(`HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}` +
+                        (snippet ? `: ${snippet}` : ''), { url, method: req.method, statusCode: response.status });
+                }
+                const data = await this.parseResponseBody(response, url, req.method);
                 // Record success in circuit breaker
                 if (this.config.circuitBreaker && this.config.sourceName && response.status < 500) {
                     this.config.circuitBreaker.recordSuccess(this.config.sourceName, req.path);
@@ -105,10 +158,21 @@ export class HttpClient {
                 if (error instanceof CircuitBreakerError) {
                     throw error;
                 }
+                // HTTP-status errors (4xx, exhausted 5xx) and body parse/size errors
+                // are definitive — don't burn retries re-fetching them.
+                if (error instanceof FetchError && error.statusCode !== undefined) {
+                    throw error;
+                }
                 // Record network errors in circuit breaker
                 if (this.config.circuitBreaker && this.config.sourceName) {
                     this.config.circuitBreaker.recordFailure(this.config.sourceName, req.path, undefined, true);
                 }
+                // A network error on a non-idempotent write is ambiguous: the request
+                // may have reached the server and committed before the socket dropped.
+                // Surface the error rather than blindly re-sending a duplicate write.
+                if (!retriable) {
+                    throw lastError;
+                }
                 if (attempt < maxAttempts) {
                     const delay = this.calculateDelay(attempt, backoff, initialDelay, maxDelay);
                     await sleep(delay);
@@ -117,6 +181,100 @@ export class HttpClient {
         }
         throw lastError ?? new Error('Request failed after all retries');
     }
+    /**
+     * Run a fetch with a per-attempt timeout. Aborts the request (freeing the
+     * connection and rate-limiter slot) if it exceeds `timeoutMs`, surfacing a
+     * retryable FetchError rather than hanging forever.
+     */
+    async fetchWithTimeout(url, options, timeoutMs, method) {
+        if (!timeoutMs || timeoutMs <= 0) {
+            return fetch(url, options);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await fetch(url, { ...options, signal: controller.signal });
+        }
+        catch (error) {
+            if (error.name === 'AbortError') {
+                throw new FetchError(`Request timed out after ${timeoutMs}ms`, {
+                    url,
+                    method,
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Parse a successful (2xx) response body. Handles empty/204 responses,
+     * returns non-JSON content as raw text, and caps the buffered size.
+     */
+    async parseResponseBody(response, url, method) {
+        // No-content responses have no body to parse.
+        if (response.status === 204 || response.status === 205) {
+            return null;
+        }
+        const text = await this.readCappedText(response, url, method);
+        if (text.trim() === '') {
+            return null;
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        const looksJson = contentType === '' || contentType.includes('json');
+        try {
+            return JSON.parse(text);
+        }
+        catch (parseError) {
+            // A non-JSON content-type (text/html, text/plain, …) is returned as-is
+            // rather than throwing — only fail when the body claimed to be JSON.
+            if (!looksJson) {
+                return text;
+            }
+            throw new FetchError(`Failed to parse JSON response (content-type '${contentType}'): ${parseError.message}`, { url, method, statusCode: response.status, cause: parseError });
+        }
+    }
+    /** Read a response body to text, rejecting once it exceeds MAX_RESPONSE_BYTES. */
+    async readCappedText(response, url, method) {
+        const body = response.body;
+        if (!body) {
+            return await response.text();
+        }
+        const reader = body.getReader();
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                size += value.byteLength;
+                if (size > MAX_RESPONSE_BYTES) {
+                    await reader.cancel();
+                    throw new FetchError(`Response body exceeds ${MAX_RESPONSE_BYTES} bytes`, {
+                        url,
+                        method,
+                        statusCode: response.status,
+                    });
+                }
+                chunks.push(Buffer.from(value));
+            }
+        }
+        return Buffer.concat(chunks).toString('utf-8');
+    }
+    /** Read a short snippet of a body for an error message (best-effort). */
+    async safeReadSnippet(response) {
+        try {
+            const text = await response.text();
+            const trimmed = text.trim();
+            return trimmed.length > 200 ? `${trimmed.slice(0, 200)}…` : trimmed;
+        }
+        catch {
+            return '';
+        }
+    }
     buildUrl(path, query) {
         const base = this.config.baseUrl.replace(/\/$/, '');
         const cleanPath = path.startsWith('/') ? path : `/${path}`;
@@ -176,6 +334,8 @@ export class OAuth2AuthProvider {
     tokenEndpoint;
     clientId;
     clientSecret;
+    /** Single-flight guard: coalesces concurrent refreshes into one in-flight request */
+    refreshPromise = null;
     constructor(config) {
         this.accessToken = config.accessToken;
         this.refreshTokenValue = config.refreshToken;
@@ -187,6 +347,21 @@ export class OAuth2AuthProvider {
         return this.accessToken;
     }
     async refreshToken() {
+        // Deduplicate concurrent refresh requests. With rotating refresh tokens,
+        // letting many in-flight requests each POST to the token endpoint would
+        // 400 invalid_grant all but one and kill the session.
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.doRefresh();
+        try {
+            return await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    async doRefresh() {
         if (!this.refreshTokenValue || !this.tokenEndpoint) {
             throw new Error('Cannot refresh token: missing refresh token or endpoint');
         }
@@ -200,7 +375,7 @@ export class OAuth2AuthProvider {
                 client_secret: this.clientSecret ?? '',
             }),
         });
-        const data = await response.json();
+        const data = (await response.json());
         this.accessToken = data.access_token;
         if (data.refresh_token) {
             this.refreshTokenValue = data.refresh_token;

package/dist/interpreter/index.d.ts

@@ -1,6 +1,8 @@
-export { MissionExecutor, type ExecutionResult, type ExecutionError, type ExecutorConfig, type ProgressCallbacks, type ExecutionStartEvent, type ExecutionCompleteEvent, type StageStartEvent, type StageCompleteEvent, } from './executor.js';
-export { HttpClient, BearerAuthProvider, OAuth2AuthProvider, type HttpClientConfig, type AuthProvider } from './http.js';
-export { createContext, childContext, getVariable, setVariable, type ExecutionContext } from './context.js';
+export { MissionExecutor, type ExecutionResult, type ExecutionError, type ExecutorConfig, type ProgressCallbacks, type ExecutionStartEvent, type ExecutionCompleteEvent, type StageStartEvent, type StageCompleteEvent, type AuthConfig, } from './executor.js';
+export { HttpClient, BearerAuthProvider, OAuth2AuthProvider, type HttpClientConfig, type AuthProvider, } from './http.js';
+export { SourceManager, type SourceManagerConfig, type SourceManagerDeps, } from './source-manager.js';
+export { StoreManager, type StoreManagerConfig } from './store-manager.js';
+export { createContext, childContext, getVariable, setVariable, type ExecutionContext, } from './context.js';
 export { evaluate, evaluateToString, interpolatePath } from './evaluator.js';
 export { FetchHandler, type FetchHandlerDeps, type FetchResult } from './fetch-handler.js';
 export { type PaginationStrategy, type PaginationContext, type PageResult, createPaginationStrategy, OffsetPaginationStrategy, PageNumberPaginationStrategy, CursorPaginationStrategy, } from './pagination.js';

package/dist/interpreter/index.js

@@ -1,6 +1,8 @@
 export { MissionExecutor, } from './executor.js';
-export { HttpClient, BearerAuthProvider, OAuth2AuthProvider } from './http.js';
-export { createContext, childContext, getVariable, setVariable } from './context.js';
+export { HttpClient, BearerAuthProvider, OAuth2AuthProvider, } from './http.js';
+export { SourceManager, } from './source-manager.js';
+export { StoreManager } from './store-manager.js';
+export { createContext, childContext, getVariable, setVariable, } from './context.js';
 export { evaluate, evaluateToString, interpolatePath } from './evaluator.js';
 export { FetchHandler } from './fetch-handler.js';
 export { createPaginationStrategy, OffsetPaginationStrategy, PageNumberPaginationStrategy, CursorPaginationStrategy, } from './pagination.js';

package/dist/interpreter/pagination.d.ts

@@ -23,8 +23,13 @@ export interface PaginationStrategy {
     buildQuery(ctx: PaginationContext): Record<string, string>;
     /** Extract results and determine if more pages exist */
     extractResults(response: unknown, ctx: PaginationContext): PageResult;
+    /** Clear any cached state (for reuse across different responses) */
+    clearCache?(): void;
 }
-/** Clear the array field cache (useful for testing) */
+/**
+ * @deprecated Use strategy.clearCache() instead. Kept for backward compatibility.
+ * Note: This now only clears the global compatibility cache, not instance caches.
+ */
 export declare function clearPaginationCache(): void;
 /**
  * Offset-based pagination (e.g., offset=100, offset=200)
@@ -32,9 +37,11 @@ export declare function clearPaginationCache(): void;
 export declare class OffsetPaginationStrategy implements PaginationStrategy {
     private config;
     private cacheKey;
+    private cache;
     constructor(config: PaginationConfig);
     buildQuery(ctx: PaginationContext): Record<string, string>;
     extractResults(response: unknown, ctx: PaginationContext): PageResult;
+    clearCache(): void;
 }
 /**
  * Page number pagination (e.g., page=1, page=2)
@@ -42,20 +49,22 @@ export declare class OffsetPaginationStrategy implements PaginationStrategy {
 export declare class PageNumberPaginationStrategy implements PaginationStrategy {
     private config;
     private cacheKey;
+    private cache;
     constructor(config: PaginationConfig);
     buildQuery(ctx: PaginationContext): Record<string, string>;
     extractResults(response: unknown, ctx: PaginationContext): PageResult;
+    clearCache(): void;
 }
 /**
  * Cursor-based pagination (e.g., cursor=abc123)
  */
 export declare class CursorPaginationStrategy implements PaginationStrategy {
     private config;
-    private cacheKey;
     private cachedArrayField;
     constructor(config: PaginationConfig);
     buildQuery(ctx: PaginationContext): Record<string, string>;
-    extractResults(response: unknown, ctx: PaginationContext): PageResult;
+    extractResults(response: unknown, _ctx: PaginationContext): PageResult;
+    clearCache(): void;
 }
 /**
  * Create the appropriate pagination strategy based on config

package/dist/interpreter/pagination.js

@@ -1,40 +1,91 @@
 import { extractNestedValue } from '../utils/path.js';
-/** Cache for discovered array field keys to avoid repeated lookups */
-const arrayFieldCache = new Map();
+/** Default TTL for cache entries (5 minutes) */
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
+/** Maximum number of cache entries before cleanup */
+const MAX_CACHE_ENTRIES = 100;
+/**
+ * Instance-level cache for array field discovery.
+ * Each pagination strategy instance has its own cache to avoid global state pollution.
+ */
+class ArrayFieldCache {
+    cache = new Map();
+    ttlMs;
+    constructor(ttlMs = DEFAULT_CACHE_TTL_MS) {
+        this.ttlMs = ttlMs;
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        // Check if expired
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        // Cleanup if cache is getting too large
+        if (this.cache.size >= MAX_CACHE_ENTRIES) {
+            this.cleanup();
+        }
+        this.cache.set(key, {
+            value,
+            expiresAt: Date.now() + this.ttlMs,
+        });
+    }
+    clear() {
+        this.cache.clear();
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+            }
+        }
+        // If still too large, remove oldest half
+        if (this.cache.size >= MAX_CACHE_ENTRIES) {
+            const entries = Array.from(this.cache.entries());
+            entries.sort((a, b) => a[1].expiresAt - b[1].expiresAt);
+            const toRemove = entries.slice(0, Math.floor(entries.length / 2));
+            for (const [key] of toRemove) {
+                this.cache.delete(key);
+            }
+        }
+    }
+}
 /**
  * Extract items array from response and determine if more pages exist
  * Shared utility for offset and page-based pagination strategies
- * Caches the discovered array field for subsequent pages
  */
-function extractItemsFromResponse(response, pageSize, cacheKey) {
+function extractItemsFromResponse(response, pageSize, cacheKey, cache) {
     if (!response || typeof response !== 'object') {
         return { items: [], hasMore: false };
     }
     const data = response;
-    // Check cache first if we have a cache key
-    if (cacheKey) {
-        const cachedField = arrayFieldCache.get(cacheKey);
-        if (cachedField !== undefined) {
-            if (cachedField === null) {
-                return { items: [], hasMore: false };
-            }
-            const items = data[cachedField];
-            if (Array.isArray(items)) {
-                return {
-                    items,
-                    hasMore: items.length >= pageSize,
-                };
-            }
+    // Check cache first
+    const cachedField = cache.get(cacheKey);
+    if (cachedField !== undefined) {
+        if (cachedField === null) {
+            return { items: [], hasMore: false };
+        }
+        const items = data[cachedField];
+        if (Array.isArray(items)) {
+            return {
+                items,
+                hasMore: items.length >= pageSize,
+            };
         }
+        // Cached field no longer valid, clear it
+        cache.clear();
     }
     // Search for array field
     for (const key of Object.keys(data)) {
         if (Array.isArray(data[key])) {
             const items = data[key];
-            // Cache the discovered field
-            if (cacheKey) {
-                arrayFieldCache.set(cacheKey, key);
-            }
+            cache.set(cacheKey, key);
             return {
                 items,
                 hasMore: items.length >= pageSize,
@@ -42,14 +93,16 @@ function extractItemsFromResponse(response, pageSize, cacheKey) {
         }
     }
     // Cache negative result
-    if (cacheKey) {
-        arrayFieldCache.set(cacheKey, null);
-    }
+    cache.set(cacheKey, null);
     return { items: [], hasMore: false };
 }
-/** Clear the array field cache (useful for testing) */
+/**
+ * @deprecated Use strategy.clearCache() instead. Kept for backward compatibility.
+ * Note: This now only clears the global compatibility cache, not instance caches.
+ */
 export function clearPaginationCache() {
-    arrayFieldCache.clear();
+    // No-op - caches are now instance-level
+    // Individual strategies should call clearCache() if needed
 }
 /**
  * Offset-based pagination (e.g., offset=100, offset=200)
@@ -57,9 +110,11 @@ export function clearPaginationCache() {
 export class OffsetPaginationStrategy {
     config;
     cacheKey;
+    cache;
     constructor(config) {
         this.config = config;
         this.cacheKey = `offset:${config.param}`;
+        this.cache = new ArrayFieldCache();
     }
     buildQuery(ctx) {
         return {
@@ -67,7 +122,10 @@ export class OffsetPaginationStrategy {
         };
     }
     extractResults(response, ctx) {
-        return extractItemsFromResponse(response, ctx.pageSize, this.cacheKey);
+        return extractItemsFromResponse(response, ctx.pageSize, this.cacheKey, this.cache);
+    }
+    clearCache() {
+        this.cache.clear();
     }
 }
 /**
@@ -76,9 +134,11 @@ export class OffsetPaginationStrategy {
 export class PageNumberPaginationStrategy {
     config;
     cacheKey;
+    cache;
     constructor(config) {
         this.config = config;
         this.cacheKey = `page:${config.param}`;
+        this.cache = new ArrayFieldCache();
     }
     buildQuery(ctx) {
         return {
@@ -86,7 +146,10 @@ export class PageNumberPaginationStrategy {
         };
     }
     extractResults(response, ctx) {
-        return extractItemsFromResponse(response, ctx.pageSize, this.cacheKey);
+        return extractItemsFromResponse(response, ctx.pageSize, this.cacheKey, this.cache);
+    }
+    clearCache() {
+        this.cache.clear();
     }
 }
 /**
@@ -94,11 +157,9 @@ export class PageNumberPaginationStrategy {
  */
 export class CursorPaginationStrategy {
     config;
-    cacheKey;
     cachedArrayField = null;
     constructor(config) {
         this.config = config;
-        this.cacheKey = `cursor:${config.param}`;
     }
     buildQuery(ctx) {
         if (ctx.cursor) {
@@ -106,7 +167,7 @@ export class CursorPaginationStrategy {
         }
         return {};
     }
-    extractResults(response, ctx) {
+    extractResults(response, _ctx) {
         if (!response || typeof response !== 'object') {
             return { items: [], hasMore: false };
         }
@@ -137,11 +198,20 @@ export class CursorPaginationStrategy {
             nextCursor,
         };
     }
+    clearCache() {
+        this.cachedArrayField = null;
+    }
 }
 /**
  * Create the appropriate pagination strategy based on config
  */
 export function createPaginationStrategy(config) {
+    // A non-positive page size makes every page request the same offset and makes
+    // the `items.length >= pageSize` termination test always true, so pagination
+    // re-fetches page one until it hits the page cap. Reject it up front.
+    if (!Number.isFinite(config.pageSize) || config.pageSize < 1) {
+        throw new Error(`Pagination page size must be a positive integer, got ${config.pageSize}`);
+    }
     switch (config.type) {
         case 'offset':
             return new OffsetPaginationStrategy(config);

package/dist/interpreter/signals.d.ts

@@ -55,3 +55,11 @@ export declare class NoMatchError extends Error {
 export declare class AbortError extends Error {
     constructor(message?: string);
 }
+/**
+ * Signal thrown when execution is paused by external control or pause step
+ */
+export declare class PauseSignal extends Error {
+    /** Pause ID if created by a pause step */
+    pauseId?: string;
+    constructor(pauseId?: string);
+}

package/dist/interpreter/signals.js

@@ -71,3 +71,15 @@ export class AbortError extends Error {
         this.name = 'AbortError';
     }
 }
+/**
+ * Signal thrown when execution is paused by external control or pause step
+ */
+export class PauseSignal extends Error {
+    /** Pause ID if created by a pause step */
+    pauseId;
+    constructor(pauseId) {
+        super(pauseId ? `Execution paused (${pauseId})` : 'Execution paused');
+        this.name = 'PauseSignal';
+        this.pauseId = pauseId;
+    }
+}