@tiangong-lca/cli 0.1.1 → 0.1.2

package/dist/src/lib/batch/attempt-recovery.js

@@ -0,0 +1,183 @@
+import { MAX_NODE_TIMER_DELAY_MS } from './canonical-contracts.js';
+import { BatchContractError, BatchMutationReplayError } from './errors.js';
+import { failedResult, freezeResult, readClock } from './scheduler-runtime.js';
+export async function executeClaim(input) {
+    const { options, index, itemContract, exclusiveKey, resumeItem, clock, sleep, emitter } = input;
+    const itemId = itemContract.item_id;
+    const item = options.items[index];
+    const resumed = resumeItem?.state === 'attempted';
+    const baseAttempts = resumed ? resumeItem.attempts : 0;
+    if (resumed && options.mode === 'mutation') {
+        const error = new BatchMutationReplayError(itemId);
+        if (!options.recoverMutation) {
+            return failedResult(item, itemContract, index, baseAttempts, true, true, clock, error, exclusiveKey);
+        }
+        return recoverMutation({
+            options,
+            item,
+            itemContract,
+            exclusiveKey,
+            index,
+            attempts: baseAttempts,
+            error,
+            source: 'resume_incomplete',
+            resumed: true,
+            clock,
+            emitter,
+        });
+    }
+    const maxAttempts = options.retry?.maxAttempts ?? 1;
+    for (let invocationAttempt = 1;; invocationAttempt += 1) {
+        const attempt = baseAttempts + invocationAttempt;
+        const context = {
+            item,
+            item_id: itemId,
+            item_contract: itemContract,
+            exclusive_key: exclusiveKey,
+            input_index: index,
+            attempt,
+            mode: options.mode,
+        };
+        await emitter.emit('attempt_started', { item_id: itemId, input_index: index, attempt });
+        try {
+            const value = await options.execute(context);
+            await emitter.emit('attempt_succeeded', { item_id: itemId, input_index: index, attempt });
+            return freezeResult({
+                item,
+                item_id: itemId,
+                item_contract: itemContract,
+                exclusive_key: exclusiveKey,
+                input_index: index,
+                attempts: attempt,
+                attempt_consumed: true,
+                resumed,
+                completed_at_ms: readClock(clock),
+                status: 'succeeded',
+                value,
+            });
+        }
+        catch (error) {
+            await emitter.emit('attempt_failed', { item_id: itemId, input_index: index, attempt });
+            if (options.mode === 'mutation') {
+                if (!options.recoverMutation) {
+                    return failedResult(item, itemContract, index, attempt, true, resumed, clock, error, exclusiveKey);
+                }
+                return recoverMutation({
+                    options,
+                    item,
+                    itemContract,
+                    exclusiveKey,
+                    index,
+                    attempts: attempt,
+                    error,
+                    source: 'execution_error',
+                    resumed,
+                    clock,
+                    emitter,
+                });
+            }
+            if (!options.retry || invocationAttempt >= maxAttempts) {
+                return failedResult(item, itemContract, index, attempt, true, resumed, clock, error, exclusiveKey);
+            }
+            const retryContext = { ...context, error };
+            let retry = false;
+            try {
+                retry = await options.retry.shouldRetry(retryContext);
+            }
+            catch (classificationError) {
+                return failedResult(item, itemContract, index, attempt, true, resumed, clock, classificationError, exclusiveKey);
+            }
+            if (!retry) {
+                return failedResult(item, itemContract, index, attempt, true, resumed, clock, error, exclusiveKey);
+            }
+            let requestedDelay;
+            try {
+                requestedDelay = await options.retry.delayMs(retryContext);
+                if (!Number.isSafeInteger(requestedDelay) ||
+                    requestedDelay < 0 ||
+                    requestedDelay > MAX_NODE_TIMER_DELAY_MS) {
+                    throw new BatchContractError(`Batch retry delay must be a non-negative safe integer no greater than the maximum supported timer delay (${MAX_NODE_TIMER_DELAY_MS} ms).`);
+                }
+            }
+            catch (delayError) {
+                return failedResult(item, itemContract, index, attempt, true, resumed, clock, delayError, exclusiveKey);
+            }
+            const delay = Math.min(requestedDelay, options.retry.maxDelayMs);
+            await emitter.emit('retry_scheduled', {
+                item_id: itemId,
+                input_index: index,
+                attempt,
+                delay_ms: delay,
+            });
+            try {
+                await sleep(delay);
+            }
+            catch (sleepError) {
+                return failedResult(item, itemContract, index, attempt, true, resumed, clock, sleepError, exclusiveKey);
+            }
+        }
+    }
+}
+async function recoverMutation(input) {
+    const { options, item, itemContract, exclusiveKey, index, attempts, error, source, resumed, clock, emitter, } = input;
+    const itemId = itemContract.item_id;
+    await emitter.emit('recovery_started', {
+        item_id: itemId,
+        input_index: index,
+        attempt: attempts,
+        source,
+    });
+    try {
+        const recovery = await options.recoverMutation({
+            item,
+            item_id: itemId,
+            item_contract: itemContract,
+            exclusive_key: exclusiveKey,
+            input_index: index,
+            attempts,
+            error,
+            source,
+        });
+        if (recovery.status === 'recovered') {
+            await emitter.emit('recovery_succeeded', {
+                item_id: itemId,
+                input_index: index,
+                attempt: attempts,
+                source,
+            });
+            return freezeResult({
+                item,
+                item_id: itemId,
+                item_contract: itemContract,
+                exclusive_key: exclusiveKey,
+                input_index: index,
+                attempts,
+                attempt_consumed: true,
+                resumed,
+                completed_at_ms: readClock(clock),
+                status: 'recovered',
+                value: recovery.value,
+            });
+        }
+        if (recovery.status !== 'unresolved') {
+            throw new BatchContractError('Mutation recovery returned an unsupported status.');
+        }
+        await emitter.emit('recovery_failed', {
+            item_id: itemId,
+            input_index: index,
+            attempt: attempts,
+            source,
+        });
+        return failedResult(item, itemContract, index, attempts, true, resumed, clock, recovery.error ?? error, exclusiveKey);
+    }
+    catch (recoveryError) {
+        await emitter.emit('recovery_failed', {
+            item_id: itemId,
+            input_index: index,
+            attempt: attempts,
+            source,
+        });
+        return failedResult(item, itemContract, index, attempts, true, resumed, clock, recoveryError, exclusiveKey);
+    }
+}
+//# sourceMappingURL=attempt-recovery.js.map

package/dist/src/lib/batch/attempt-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt-recovery.js","sourceRoot":"","sources":["../../../../src/lib/batch/attempt-recovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAqB,MAAM,wBAAwB,CAAC;AAclG,MAAM,CAAC,KAAK,UAAU,YAAY,CAKhC,KASD;IACC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAChG,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAE,CAAC;IACnC,MAAM,OAAO,GAAG,UAAU,EAAE,KAAK,KAAK,WAAW,CAAC;IAClD,MAAM,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,IAAI,wBAAwB,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;YAC7B,OAAO,YAAY,CACjB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,YAAY,EACZ,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,KAAK,EACL,YAAY,CACb,CAAC;QACJ,CAAC;QACD,OAAO,eAAe,CAAC;YACrB,OAAO;YACP,IAAI;YACJ,YAAY;YACZ,YAAY;YACZ,KAAK;YACL,QAAQ,EAAE,YAAY;YACtB,KAAK;YACL,MAAM,EAAE,mBAAmB;YAC3B,OAAO,EAAE,IAAI;YACb,KAAK;YACL,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,EAAE,WAAW,IAAI,CAAC,CAAC;IACpD,KAAK,IAAI,iBAAiB,GAAG,CAAC,GAAI,iBAAiB,IAAI,CAAC,EAAE,CAAC;QACzD,MAAM,OAAO,GAAG,YAAY,GAAG,iBAAiB,CAAC;QACjD,MAAM,OAAO,GAAiD;YAC5D,IAAI;YACJ,OAAO,EAAE,MAAM;YACf,aAAa,EAAE,YAAY;YAC3B,aAAa,EAAE,YAAY;YAC3B,WAAW,EAAE,KAAK;YAClB,OAAO;YACP,IAAI,EAAE,OAAO,CAAC,IAAI;SACnB,CAAC;QACF,MAAM,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QACxF,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC7C,MAAM,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YAC1F,OAAO,YAAY,CAAC;gBAClB,IAAI;gBACJ,OAAO,EAAE,MAAM;gBACf,aAAa,EAAE,YAAY;gBAC3B,aAAa,EAAE,YAAY;gBAC3B,WAAW,EAAE,KAAK;gBAClB,QAAQ,EAAE,OAAO;gBACjB,gBAAgB,EAAE,IAAI;gBACtB,OAAO;gBACP,eAAe,EAAE,SAAS,CAAC,KAAK,CAAC;gBACjC,MAAM,EAAE,WAAW;gBACnB,KAAK;aACN,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YACvF,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAChC,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;oBAC7B,OAAO,YAAY,CACjB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,OAAO,EACP,IAAI,EACJ,OAAO,EACP,KAAK,EACL,KAAK,EACL,YAAY,CACb,CAAC;gBACJ,CAAC;gBACD,OAAO,eAAe,CAAC;oBACrB,OAAO;oBACP,IAAI;oBACJ,YAAY;oBACZ,YAAY;oBACZ,KAAK;oBACL,QAAQ,EAAE,OAAO;oBACjB,KAAK;oBACL,MAAM,EAAE,iBAAiB;oBACzB,OAAO;oBACP,KAAK;oBACL,OAAO;iBACR,CAAC,CAAC;YACL,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,iBAAiB,IAAI,WAAW,EAAE,CAAC;gBACvD,OAAO,YAAY,CACjB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,OAAO,EACP,IAAI,EACJ,OAAO,EACP,KAAK,EACL,KAAK,EACL,YAAY,CACb,CAAC;YACJ,CAAC;YACD,MAAM,YAAY,GAA6C,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC;YACrF,IAAI,KAAK,GAAG,KAAK,CAAC;YAClB,IAAI,CAAC;gBACH,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;YACxD,CAAC;YAAC,OAAO,mBAAmB,EAAE,CAAC;gBAC7B,OAAO,YAAY,CACjB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,OAAO,EACP,IAAI,EACJ,OAAO,EACP,KAAK,EACL,mBAAmB,EACnB,YAAY,CACb,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,YAAY,CACjB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,OAAO,EACP,IAAI,EACJ,OAAO,EACP,KAAK,EACL,KAAK,EACL,YAAY,CACb,CAAC;YACJ,CAAC;YACD,IAAI,cAAsB,CAAC;YAC3B,IAAI,CAAC;gBACH,cAAc,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;gBAC3D,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC;oBACrC,cAAc,GAAG,CAAC;oBAClB,cAAc,GAAG,uBAAuB,EACxC,CAAC;oBACD,MAAM,IAAI,kBAAkB,CAC1B,4GAA4G,uBAAuB,OAAO,CAC3I,CAAC;gBACJ,CAAC;YACH,CAAC;YAAC,OAAO,UAAU,EAAE,CAAC;gBACpB,OAAO,YAAY,CACjB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,OAAO,EACP,IAAI,EACJ,OAAO,EACP,KAAK,EACL,UAAU,EACV,YAAY,CACb,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACjE,MAAM,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE;gBACpC,OAAO,EAAE,MAAM;gBACf,WAAW,EAAE,KAAK;gBAClB,OAAO;gBACP,QAAQ,EAAE,KAAK;aAChB,CAAC,CAAC;YACH,IAAI,CAAC;gBACH,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;YAAC,OAAO,UAAU,EAAE,CAAC;gBACpB,OAAO,YAAY,CACjB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,OAAO,EACP,IAAI,EACJ,OAAO,EACP,KAAK,EACL,UAAU,EACV,YAAY,CACb,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,eAAe,CAK5B,KAYD;IACC,MAAM,EACJ,OAAO,EACP,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,KAAK,EACL,MAAM,EACN,OAAO,EACP,KAAK,EACL,OAAO,GACR,GAAG,KAAK,CAAC;IACV,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC;IACpC,MAAM,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE;QACrC,OAAO,EAAE,MAAM;QACf,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,QAAQ;QACjB,MAAM;KACP,CAAC,CAAC;IACH,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,eAAgB,CAAC;YAC9C,IAAI;YACJ,OAAO,EAAE,MAAM;YACf,aAAa,EAAE,YAAY;YAC3B,aAAa,EAAE,YAAY;YAC3B,WAAW,EAAE,KAAK;YAClB,QAAQ;YACR,KAAK;YACL,MAAM;SACP,CAAC,CAAC;QACH,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YACpC,MAAM,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE;gBACvC,OAAO,EAAE,MAAM;gBACf,WAAW,EAAE,KAAK;gBAClB,OAAO,EAAE,QAAQ;gBACjB,MAAM;aACP,CAAC,CAAC;YACH,OAAO,YAAY,CAAC;gBAClB,IAAI;gBACJ,OAAO,EAAE,MAAM;gBACf,aAAa,EAAE,YAAY;gBAC3B,aAAa,EAAE,YAAY;gBAC3B,WAAW,EAAE,KAAK;gBAClB,QAAQ;gBACR,gBAAgB,EAAE,IAAI;gBACtB,OAAO;gBACP,eAAe,EAAE,SAAS,CAAC,KAAK,CAAC;gBACjC,MAAM,EAAE,WAAW;gBACnB,KAAK,EAAE,QAAQ,CAAC,KAAK;aACtB,CAAC,CAAC;QACL,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,KAAK,YAAY,EAAE,CAAC;YACrC,MAAM,IAAI,kBAAkB,CAAC,mDAAmD,CAAC,CAAC;QACpF,CAAC;QACD,MAAM,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE;YACpC,OAAO,EAAE,MAAM;YACf,WAAW,EAAE,KAAK;YAClB,OAAO,EAAE,QAAQ;YACjB,MAAM;SACP,CAAC,CAAC;QACH,OAAO,YAAY,CACjB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,KAAK,EACL,QAAQ,CAAC,KAAK,IAAI,KAAK,EACvB,YAAY,CACb,CAAC;IACJ,CAAC;IAAC,OAAO,aAAa,EAAE,CAAC;QACvB,MAAM,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE;YACpC,OAAO,EAAE,MAAM;YACf,WAAW,EAAE,KAAK;YAClB,OAAO,EAAE,QAAQ;YACjB,MAAM;SACP,CAAC,CAAC;QACH,OAAO,YAAY,CACjB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,KAAK,EACL,aAAa,EACb,YAAY,CACb,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import { MAX_NODE_TIMER_DELAY_MS } from './canonical-contracts.js';\nimport { BatchContractError, BatchMutationReplayError } from './errors.js';\nimport { failedResult, freezeResult, readClock, type EventEmitter } from './scheduler-runtime.js';\nimport type {\n  BatchClock,\n  BatchExecutionContext,\n  BatchItemContract,\n  BatchItemResult,\n  BatchJsonValue,\n  BatchRecoverySource,\n  BatchResumeItem,\n  BatchRetryContext,\n  BatchSleep,\n  RunBoundedBatchOptions,\n} from './types.js';\n\nexport async function executeClaim<\n  TInput,\n  TOutput,\n  TIdentity extends BatchJsonValue,\n  TExclusiveKey extends string,\n>(input: {\n  options: RunBoundedBatchOptions<TInput, TOutput, TIdentity, TExclusiveKey>;\n  index: number;\n  itemContract: BatchItemContract;\n  exclusiveKey: TExclusiveKey | null;\n  resumeItem: BatchResumeItem<TOutput> | undefined;\n  clock: BatchClock;\n  sleep: BatchSleep;\n  emitter: EventEmitter;\n}): Promise<BatchItemResult<TInput, TOutput>> {\n  const { options, index, itemContract, exclusiveKey, resumeItem, clock, sleep, emitter } = input;\n  const itemId = itemContract.item_id;\n  const item = options.items[index]!;\n  const resumed = resumeItem?.state === 'attempted';\n  const baseAttempts = resumed ? resumeItem.attempts : 0;\n  if (resumed && options.mode === 'mutation') {\n    const error = new BatchMutationReplayError(itemId);\n    if (!options.recoverMutation) {\n      return failedResult(\n        item,\n        itemContract,\n        index,\n        baseAttempts,\n        true,\n        true,\n        clock,\n        error,\n        exclusiveKey,\n      );\n    }\n    return recoverMutation({\n      options,\n      item,\n      itemContract,\n      exclusiveKey,\n      index,\n      attempts: baseAttempts,\n      error,\n      source: 'resume_incomplete',\n      resumed: true,\n      clock,\n      emitter,\n    });\n  }\n\n  const maxAttempts = options.retry?.maxAttempts ?? 1;\n  for (let invocationAttempt = 1; ; invocationAttempt += 1) {\n    const attempt = baseAttempts + invocationAttempt;\n    const context: BatchExecutionContext<TInput, TExclusiveKey> = {\n      item,\n      item_id: itemId,\n      item_contract: itemContract,\n      exclusive_key: exclusiveKey,\n      input_index: index,\n      attempt,\n      mode: options.mode,\n    };\n    await emitter.emit('attempt_started', { item_id: itemId, input_index: index, attempt });\n    try {\n      const value = await options.execute(context);\n      await emitter.emit('attempt_succeeded', { item_id: itemId, input_index: index, attempt });\n      return freezeResult({\n        item,\n        item_id: itemId,\n        item_contract: itemContract,\n        exclusive_key: exclusiveKey,\n        input_index: index,\n        attempts: attempt,\n        attempt_consumed: true,\n        resumed,\n        completed_at_ms: readClock(clock),\n        status: 'succeeded',\n        value,\n      });\n    } catch (error) {\n      await emitter.emit('attempt_failed', { item_id: itemId, input_index: index, attempt });\n      if (options.mode === 'mutation') {\n        if (!options.recoverMutation) {\n          return failedResult(\n            item,\n            itemContract,\n            index,\n            attempt,\n            true,\n            resumed,\n            clock,\n            error,\n            exclusiveKey,\n          );\n        }\n        return recoverMutation({\n          options,\n          item,\n          itemContract,\n          exclusiveKey,\n          index,\n          attempts: attempt,\n          error,\n          source: 'execution_error',\n          resumed,\n          clock,\n          emitter,\n        });\n      }\n      if (!options.retry || invocationAttempt >= maxAttempts) {\n        return failedResult(\n          item,\n          itemContract,\n          index,\n          attempt,\n          true,\n          resumed,\n          clock,\n          error,\n          exclusiveKey,\n        );\n      }\n      const retryContext: BatchRetryContext<TInput, TExclusiveKey> = { ...context, error };\n      let retry = false;\n      try {\n        retry = await options.retry.shouldRetry(retryContext);\n      } catch (classificationError) {\n        return failedResult(\n          item,\n          itemContract,\n          index,\n          attempt,\n          true,\n          resumed,\n          clock,\n          classificationError,\n          exclusiveKey,\n        );\n      }\n      if (!retry) {\n        return failedResult(\n          item,\n          itemContract,\n          index,\n          attempt,\n          true,\n          resumed,\n          clock,\n          error,\n          exclusiveKey,\n        );\n      }\n      let requestedDelay: number;\n      try {\n        requestedDelay = await options.retry.delayMs(retryContext);\n        if (\n          !Number.isSafeInteger(requestedDelay) ||\n          requestedDelay < 0 ||\n          requestedDelay > MAX_NODE_TIMER_DELAY_MS\n        ) {\n          throw new BatchContractError(\n            `Batch retry delay must be a non-negative safe integer no greater than the maximum supported timer delay (${MAX_NODE_TIMER_DELAY_MS} ms).`,\n          );\n        }\n      } catch (delayError) {\n        return failedResult(\n          item,\n          itemContract,\n          index,\n          attempt,\n          true,\n          resumed,\n          clock,\n          delayError,\n          exclusiveKey,\n        );\n      }\n      const delay = Math.min(requestedDelay, options.retry.maxDelayMs);\n      await emitter.emit('retry_scheduled', {\n        item_id: itemId,\n        input_index: index,\n        attempt,\n        delay_ms: delay,\n      });\n      try {\n        await sleep(delay);\n      } catch (sleepError) {\n        return failedResult(\n          item,\n          itemContract,\n          index,\n          attempt,\n          true,\n          resumed,\n          clock,\n          sleepError,\n          exclusiveKey,\n        );\n      }\n    }\n  }\n}\n\nasync function recoverMutation<\n  TInput,\n  TOutput,\n  TIdentity extends BatchJsonValue,\n  TExclusiveKey extends string,\n>(input: {\n  options: RunBoundedBatchOptions<TInput, TOutput, TIdentity, TExclusiveKey>;\n  item: TInput;\n  itemContract: BatchItemContract;\n  exclusiveKey: TExclusiveKey | null;\n  index: number;\n  attempts: number;\n  error: unknown;\n  source: BatchRecoverySource;\n  resumed: boolean;\n  clock: BatchClock;\n  emitter: EventEmitter;\n}): Promise<BatchItemResult<TInput, TOutput>> {\n  const {\n    options,\n    item,\n    itemContract,\n    exclusiveKey,\n    index,\n    attempts,\n    error,\n    source,\n    resumed,\n    clock,\n    emitter,\n  } = input;\n  const itemId = itemContract.item_id;\n  await emitter.emit('recovery_started', {\n    item_id: itemId,\n    input_index: index,\n    attempt: attempts,\n    source,\n  });\n  try {\n    const recovery = await options.recoverMutation!({\n      item,\n      item_id: itemId,\n      item_contract: itemContract,\n      exclusive_key: exclusiveKey,\n      input_index: index,\n      attempts,\n      error,\n      source,\n    });\n    if (recovery.status === 'recovered') {\n      await emitter.emit('recovery_succeeded', {\n        item_id: itemId,\n        input_index: index,\n        attempt: attempts,\n        source,\n      });\n      return freezeResult({\n        item,\n        item_id: itemId,\n        item_contract: itemContract,\n        exclusive_key: exclusiveKey,\n        input_index: index,\n        attempts,\n        attempt_consumed: true,\n        resumed,\n        completed_at_ms: readClock(clock),\n        status: 'recovered',\n        value: recovery.value,\n      });\n    }\n    if (recovery.status !== 'unresolved') {\n      throw new BatchContractError('Mutation recovery returned an unsupported status.');\n    }\n    await emitter.emit('recovery_failed', {\n      item_id: itemId,\n      input_index: index,\n      attempt: attempts,\n      source,\n    });\n    return failedResult(\n      item,\n      itemContract,\n      index,\n      attempts,\n      true,\n      resumed,\n      clock,\n      recovery.error ?? error,\n      exclusiveKey,\n    );\n  } catch (recoveryError) {\n    await emitter.emit('recovery_failed', {\n      item_id: itemId,\n      input_index: index,\n      attempt: attempts,\n      source,\n    });\n    return failedResult(\n      item,\n      itemContract,\n      index,\n      attempts,\n      true,\n      resumed,\n      clock,\n      recoveryError,\n      exclusiveKey,\n    );\n  }\n}\n"]}

package/dist/src/lib/batch/canonical-contracts.d.ts

@@ -0,0 +1,21 @@
+import type { BatchContract, BatchItemContract, BatchJsonValue, CreateBatchContractOptions, CreateBatchItemContractOptions } from './types.js';
+export declare const MAX_NODE_TIMER_DELAY_MS = 2147483647;
+export declare function canonicalBatchJson(value: BatchJsonValue): string;
+export declare function sha256BatchBytes(value: string | Uint8Array): string;
+export declare function sha256BatchJson(value: BatchJsonValue): string;
+export declare function createBatchContract<TIdentity extends BatchJsonValue>(options: CreateBatchContractOptions<TIdentity>): BatchContract<TIdentity>;
+export declare function createBatchItemContract(options: CreateBatchItemContractOptions): BatchItemContract;
+export declare function parseBatchItemContract(value: unknown): BatchItemContract;
+export declare function assertBatchItemContractMatches(expectedValue: unknown, actualValue: unknown): BatchItemContract;
+export declare function parseBatchContract<TIdentity extends BatchJsonValue = BatchJsonValue>(value: unknown): BatchContract<TIdentity>;
+export declare function assertBatchContractMatches<TIdentity extends BatchJsonValue>(expectedValue: unknown, actualValue: unknown): BatchContract<TIdentity>;
+export declare function canonicalizeBatchValue(value: unknown, ancestors: Set<object>): BatchJsonValue;
+export declare function freezeBatchJson<T extends BatchJsonValue>(value: T): T;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function parseBatchRunPath(value: unknown): string;
+export declare function parseBatchRunLockToken(value: unknown, label: string): string;
+export declare function assertBatchTimerDelaySupported(value: number | undefined, label: string): void;
+export declare function hasExactKeys(value: Record<string, unknown>, expectedKeys: readonly string[]): boolean;
+export declare function parseItemIdentity(value: unknown, location: number | 'contract'): string;
+export declare function assertUniqueItemIds(itemIds: readonly string[]): void;
+export declare function batchItemContractsMatch(left: BatchItemContract, right: BatchItemContract): boolean;

package/dist/src/lib/batch/canonical-contracts.js

@@ -0,0 +1,180 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { BatchContractError, BatchItemResumeContractError } from './errors.js';
+const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
+export const MAX_NODE_TIMER_DELAY_MS = 2_147_483_647;
+export function canonicalBatchJson(value) {
+    return JSON.stringify(canonicalizeBatchValue(value, new Set()));
+}
+export function sha256BatchBytes(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export function sha256BatchJson(value) {
+    return sha256BatchBytes(canonicalBatchJson(value));
+}
+export function createBatchContract(options) {
+    const identity = freezeBatchJson(canonicalizeBatchValue(options.identity, new Set()));
+    return Object.freeze({
+        identity,
+        content_sha256: sha256BatchJson(options.content),
+        policy_sha256: sha256BatchJson(options.policy),
+    });
+}
+export function createBatchItemContract(options) {
+    const itemId = parseItemIdentity(options.item_id, 'contract');
+    return Object.freeze({
+        item_id: itemId,
+        content_sha256: sha256BatchJson(options.content),
+        policy_sha256: sha256BatchJson(options.policy),
+    });
+}
+export function parseBatchItemContract(value) {
+    if (!isRecord(value) ||
+        typeof value.item_id !== 'string' ||
+        typeof value.content_sha256 !== 'string' ||
+        !SHA256_PATTERN.test(value.content_sha256) ||
+        typeof value.policy_sha256 !== 'string' ||
+        !SHA256_PATTERN.test(value.policy_sha256)) {
+        throw new BatchContractError('Batch item contract requires item_id plus valid content and policy SHA-256 values.');
+    }
+    return Object.freeze({
+        item_id: parseItemIdentity(value.item_id, 'contract'),
+        content_sha256: value.content_sha256,
+        policy_sha256: value.policy_sha256,
+    });
+}
+export function assertBatchItemContractMatches(expectedValue, actualValue) {
+    const expected = parseBatchItemContract(expectedValue);
+    const actual = parseBatchItemContract(actualValue);
+    if (!batchItemContractsMatch(expected, actual)) {
+        throw new BatchItemResumeContractError(expected.item_id);
+    }
+    return actual;
+}
+export function parseBatchContract(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ['content_sha256', 'identity', 'policy_sha256'])) {
+        throw new BatchContractError('Batch contract must contain exact identity, content_sha256, and policy_sha256 keys.');
+    }
+    let identity;
+    try {
+        identity = freezeBatchJson(canonicalizeBatchValue(value.identity, new Set()));
+    }
+    catch (error) {
+        throw new BatchContractError('Batch contract identity must be canonical JSON data.', {
+            cause: error,
+        });
+    }
+    if (typeof value.content_sha256 !== 'string' ||
+        !SHA256_PATTERN.test(value.content_sha256) ||
+        typeof value.policy_sha256 !== 'string' ||
+        !SHA256_PATTERN.test(value.policy_sha256)) {
+        throw new BatchContractError('Batch contract content and policy SHA-256 values are malformed.');
+    }
+    return Object.freeze({
+        identity,
+        content_sha256: value.content_sha256,
+        policy_sha256: value.policy_sha256,
+    });
+}
+export function assertBatchContractMatches(expectedValue, actualValue) {
+    const expected = parseBatchContract(expectedValue);
+    const actual = parseBatchContract(actualValue);
+    if (canonicalBatchJson(expected.identity) !== canonicalBatchJson(actual.identity) ||
+        expected.content_sha256 !== actual.content_sha256 ||
+        expected.policy_sha256 !== actual.policy_sha256) {
+        throw new BatchContractError('Batch resume requires an exact identity, content SHA-256, and policy SHA-256 match.');
+    }
+    return actual;
+}
+export function canonicalizeBatchValue(value, ancestors) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new BatchContractError('Canonical batch JSON rejects non-finite numbers.');
+        }
+        return value;
+    }
+    if (typeof value !== 'object') {
+        throw new BatchContractError('Canonical batch JSON accepts JSON data only.');
+    }
+    if (ancestors.has(value)) {
+        throw new BatchContractError('Canonical batch JSON rejects cyclic data.');
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((entry) => canonicalizeBatchValue(entry, ancestors));
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new BatchContractError('Canonical batch JSON accepts plain objects only.');
+        }
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [
+            key,
+            canonicalizeBatchValue(value[key], ancestors),
+        ]));
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+export function freezeBatchJson(value) {
+    if (value !== null && typeof value === 'object') {
+        for (const child of Object.values(value))
+            freezeBatchJson(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function parseBatchRunPath(value) {
+    if (typeof value !== 'string' || value.length === 0 || /[\0\r\n]/u.test(value)) {
+        throw new BatchContractError('Batch runPath must be a non-empty single-line path.');
+    }
+    return path.resolve(value);
+}
+export function parseBatchRunLockToken(value, label) {
+    if (typeof value !== 'string' || value.length === 0 || /[\0\r\n]/u.test(value)) {
+        throw new BatchContractError(`Batch run-lock ${label} must be a non-empty single-line string.`);
+    }
+    return value;
+}
+export function assertBatchTimerDelaySupported(value, label) {
+    if (value === undefined)
+        return;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new BatchContractError(`Batch ${label} must be a non-negative safe integer.`);
+    }
+    if (value > MAX_NODE_TIMER_DELAY_MS) {
+        throw new BatchContractError(`Batch ${label} exceeds the maximum supported timer delay (${MAX_NODE_TIMER_DELAY_MS} ms).`);
+    }
+}
+export function hasExactKeys(value, expectedKeys) {
+    const actual = Object.keys(value).sort();
+    const expected = [...expectedKeys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+export function parseItemIdentity(value, location) {
+    if (typeof value !== 'string' || value.length === 0 || /[\0\r\n]/u.test(value)) {
+        throw new BatchContractError(location === 'contract'
+            ? 'Batch item contract identity must be a non-empty single-line string.'
+            : `Batch item identity at input index ${location} must be a non-empty single-line string.`);
+    }
+    return value;
+}
+export function assertUniqueItemIds(itemIds) {
+    if (new Set(itemIds).size !== itemIds.length) {
+        throw new BatchContractError('Batch item identities must be unique.');
+    }
+}
+export function batchItemContractsMatch(left, right) {
+    return (left.item_id === right.item_id &&
+        left.content_sha256 === right.content_sha256 &&
+        left.policy_sha256 === right.policy_sha256);
+}
+//# sourceMappingURL=canonical-contracts.js.map

package/dist/src/lib/batch/canonical-contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-contracts.js","sourceRoot":"","sources":["../../../../src/lib/batch/canonical-contracts.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from 'node:crypto';\nimport path from 'node:path';\n\nimport { BatchContractError, BatchItemResumeContractError } from './errors.js';\nimport type {\n  BatchContract,\n  BatchItemContract,\n  BatchJsonValue,\n  CreateBatchContractOptions,\n  CreateBatchItemContractOptions,\n} from './types.js';\n\nconst SHA256_PATTERN = /^[a-f0-9]{64}$/u;\nexport const MAX_NODE_TIMER_DELAY_MS = 2_147_483_647;\n\nexport function canonicalBatchJson(value: BatchJsonValue): string {\n  return JSON.stringify(canonicalizeBatchValue(value, new Set<object>()));\n}\n\nexport function sha256BatchBytes(value: string | Uint8Array): string {\n  return createHash('sha256').update(value).digest('hex');\n}\n\nexport function sha256BatchJson(value: BatchJsonValue): string {\n  return sha256BatchBytes(canonicalBatchJson(value));\n}\n\nexport function createBatchContract<TIdentity extends BatchJsonValue>(\n  options: CreateBatchContractOptions<TIdentity>,\n): BatchContract<TIdentity> {\n  const identity = freezeBatchJson(\n    canonicalizeBatchValue(options.identity, new Set<object>()),\n  ) as TIdentity;\n  return Object.freeze({\n    identity,\n    content_sha256: sha256BatchJson(options.content),\n    policy_sha256: sha256BatchJson(options.policy),\n  });\n}\n\nexport function createBatchItemContract(\n  options: CreateBatchItemContractOptions,\n): BatchItemContract {\n  const itemId = parseItemIdentity(options.item_id, 'contract');\n  return Object.freeze({\n    item_id: itemId,\n    content_sha256: sha256BatchJson(options.content),\n    policy_sha256: sha256BatchJson(options.policy),\n  });\n}\n\nexport function parseBatchItemContract(value: unknown): BatchItemContract {\n  if (\n    !isRecord(value) ||\n    typeof value.item_id !== 'string' ||\n    typeof value.content_sha256 !== 'string' ||\n    !SHA256_PATTERN.test(value.content_sha256) ||\n    typeof value.policy_sha256 !== 'string' ||\n    !SHA256_PATTERN.test(value.policy_sha256)\n  ) {\n    throw new BatchContractError(\n      'Batch item contract requires item_id plus valid content and policy SHA-256 values.',\n    );\n  }\n  return Object.freeze({\n    item_id: parseItemIdentity(value.item_id, 'contract'),\n    content_sha256: value.content_sha256,\n    policy_sha256: value.policy_sha256,\n  });\n}\n\nexport function assertBatchItemContractMatches(\n  expectedValue: unknown,\n  actualValue: unknown,\n): BatchItemContract {\n  const expected = parseBatchItemContract(expectedValue);\n  const actual = parseBatchItemContract(actualValue);\n  if (!batchItemContractsMatch(expected, actual)) {\n    throw new BatchItemResumeContractError(expected.item_id);\n  }\n  return actual;\n}\n\nexport function parseBatchContract<TIdentity extends BatchJsonValue = BatchJsonValue>(\n  value: unknown,\n): BatchContract<TIdentity> {\n  if (!isRecord(value) || !hasExactKeys(value, ['content_sha256', 'identity', 'policy_sha256'])) {\n    throw new BatchContractError(\n      'Batch contract must contain exact identity, content_sha256, and policy_sha256 keys.',\n    );\n  }\n  let identity: TIdentity;\n  try {\n    identity = freezeBatchJson(\n      canonicalizeBatchValue(value.identity, new Set<object>()),\n    ) as TIdentity;\n  } catch (error) {\n    throw new BatchContractError('Batch contract identity must be canonical JSON data.', {\n      cause: error,\n    });\n  }\n  if (\n    typeof value.content_sha256 !== 'string' ||\n    !SHA256_PATTERN.test(value.content_sha256) ||\n    typeof value.policy_sha256 !== 'string' ||\n    !SHA256_PATTERN.test(value.policy_sha256)\n  ) {\n    throw new BatchContractError('Batch contract content and policy SHA-256 values are malformed.');\n  }\n  return Object.freeze({\n    identity,\n    content_sha256: value.content_sha256,\n    policy_sha256: value.policy_sha256,\n  });\n}\n\nexport function assertBatchContractMatches<TIdentity extends BatchJsonValue>(\n  expectedValue: unknown,\n  actualValue: unknown,\n): BatchContract<TIdentity> {\n  const expected = parseBatchContract<TIdentity>(expectedValue);\n  const actual = parseBatchContract<TIdentity>(actualValue);\n  if (\n    canonicalBatchJson(expected.identity) !== canonicalBatchJson(actual.identity) ||\n    expected.content_sha256 !== actual.content_sha256 ||\n    expected.policy_sha256 !== actual.policy_sha256\n  ) {\n    throw new BatchContractError(\n      'Batch resume requires an exact identity, content SHA-256, and policy SHA-256 match.',\n    );\n  }\n  return actual;\n}\n\nexport function canonicalizeBatchValue(value: unknown, ancestors: Set<object>): BatchJsonValue {\n  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;\n  if (typeof value === 'number') {\n    if (!Number.isFinite(value)) {\n      throw new BatchContractError('Canonical batch JSON rejects non-finite numbers.');\n    }\n    return value;\n  }\n  if (typeof value !== 'object') {\n    throw new BatchContractError('Canonical batch JSON accepts JSON data only.');\n  }\n  if (ancestors.has(value)) {\n    throw new BatchContractError('Canonical batch JSON rejects cyclic data.');\n  }\n  ancestors.add(value);\n  try {\n    if (Array.isArray(value)) {\n      return value.map((entry) => canonicalizeBatchValue(entry, ancestors));\n    }\n    const prototype = Object.getPrototypeOf(value);\n    if (prototype !== Object.prototype && prototype !== null) {\n      throw new BatchContractError('Canonical batch JSON accepts plain objects only.');\n    }\n    return Object.fromEntries(\n      Object.keys(value)\n        .sort()\n        .map((key) => [\n          key,\n          canonicalizeBatchValue((value as Record<string, unknown>)[key], ancestors),\n        ]),\n    );\n  } finally {\n    ancestors.delete(value);\n  }\n}\n\nexport function freezeBatchJson<T extends BatchJsonValue>(value: T): T {\n  if (value !== null && typeof value === 'object') {\n    for (const child of Object.values(value)) freezeBatchJson(child);\n    Object.freeze(value);\n  }\n  return value;\n}\n\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nexport function parseBatchRunPath(value: unknown): string {\n  if (typeof value !== 'string' || value.length === 0 || /[\\0\\r\\n]/u.test(value)) {\n    throw new BatchContractError('Batch runPath must be a non-empty single-line path.');\n  }\n  return path.resolve(value);\n}\n\nexport function parseBatchRunLockToken(value: unknown, label: string): string {\n  if (typeof value !== 'string' || value.length === 0 || /[\\0\\r\\n]/u.test(value)) {\n    throw new BatchContractError(`Batch run-lock ${label} must be a non-empty single-line string.`);\n  }\n  return value;\n}\n\nexport function assertBatchTimerDelaySupported(value: number | undefined, label: string): void {\n  if (value === undefined) return;\n  if (!Number.isSafeInteger(value) || value < 0) {\n    throw new BatchContractError(`Batch ${label} must be a non-negative safe integer.`);\n  }\n  if (value > MAX_NODE_TIMER_DELAY_MS) {\n    throw new BatchContractError(\n      `Batch ${label} exceeds the maximum supported timer delay (${MAX_NODE_TIMER_DELAY_MS} ms).`,\n    );\n  }\n}\n\nexport function hasExactKeys(\n  value: Record<string, unknown>,\n  expectedKeys: readonly string[],\n): boolean {\n  const actual = Object.keys(value).sort();\n  const expected = [...expectedKeys].sort();\n  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);\n}\n\nexport function parseItemIdentity(value: unknown, location: number | 'contract'): string {\n  if (typeof value !== 'string' || value.length === 0 || /[\\0\\r\\n]/u.test(value)) {\n    throw new BatchContractError(\n      location === 'contract'\n        ? 'Batch item contract identity must be a non-empty single-line string.'\n        : `Batch item identity at input index ${location} must be a non-empty single-line string.`,\n    );\n  }\n  return value;\n}\n\nexport function assertUniqueItemIds(itemIds: readonly string[]): void {\n  if (new Set(itemIds).size !== itemIds.length) {\n    throw new BatchContractError('Batch item identities must be unique.');\n  }\n}\n\nexport function batchItemContractsMatch(\n  left: BatchItemContract,\n  right: BatchItemContract,\n): boolean {\n  return (\n    left.item_id === right.item_id &&\n    left.content_sha256 === right.content_sha256 &&\n    left.policy_sha256 === right.policy_sha256\n  );\n}\n"]}

package/dist/src/lib/batch/engine.d.ts

@@ -0,0 +1,2 @@
+import type { BatchJsonValue, BatchRunResult, RunBoundedBatchOptions } from './types.js';
+export declare function runBoundedBatch<TInput, TOutput, TIdentity extends BatchJsonValue, TExclusiveKey extends string = string>(options: RunBoundedBatchOptions<TInput, TOutput, TIdentity, TExclusiveKey>): Promise<BatchRunResult<TInput, TOutput, TIdentity>>;