@empire-builder-kit/runtime 1.0.0-beta.8 → 1.0.0-rc.1

package/src/async-work/sqs.js

@@ -0,0 +1,280 @@
+import { __awaiter, __rest } from "tslib";
+import { asyncWorkDigest, compareAsyncStrings, failAsyncWork, requireAsyncIdentifier, requireAsyncInteger, requireAsyncNumber, requireCanonicalAsyncTimestamp, } from './contract.js';
+function normalizeRetryPolicy(policy) {
+    const normalized = {
+        attemptTimeoutMs: requireAsyncInteger(policy.attemptTimeoutMs, '/policy/attemptTimeoutMs', 1, 900000),
+        baseDelayMs: requireAsyncInteger(policy.baseDelayMs, '/policy/baseDelayMs', 1, 3600000),
+        maximumAttempts: requireAsyncInteger(policy.maximumAttempts, '/policy/maximumAttempts', 1, 100),
+        maximumDelayMs: requireAsyncInteger(policy.maximumDelayMs, '/policy/maximumDelayMs', 1, 3600000),
+        totalTimeoutMs: requireAsyncInteger(policy.totalTimeoutMs, '/policy/totalTimeoutMs', 1, 86400000),
+    };
+    if (normalized.attemptTimeoutMs >= normalized.totalTimeoutMs) {
+        failAsyncWork('async-input-invalid', '/policy/attemptTimeoutMs', 'must be shorter than the total retry budget');
+    }
+    if (normalized.baseDelayMs > normalized.maximumDelayMs) {
+        failAsyncWork('async-input-invalid', '/policy/baseDelayMs', 'must not exceed maximumDelayMs');
+    }
+    return normalized;
+}
+function timedAttempt(attempt, attemptNumber, timeoutMs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const controller = new AbortController();
+        let timeout;
+        try {
+            return yield Promise.race([
+                attempt({ attempt: attemptNumber, signal: controller.signal }),
+                new Promise((resolve) => {
+                    timeout = setTimeout(() => {
+                        resolve({ errorCode: 'attempt-timeout', outcome: 'retryable' });
+                        controller.abort();
+                    }, timeoutMs);
+                }),
+            ]);
+        }
+        catch (_a) {
+            return { errorCode: 'unhandled-attempt-error', outcome: 'retryable' };
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+        }
+    });
+}
+/**
+ * Applies a single bounded retry budget with full jitter. SDK retries should
+ * be disabled or included in this declared total attempt budget.
+ */
+export function executeWithRetry(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const policy = normalizeRetryPolicy(input.policy);
+        const now = (_a = input.now) !== null && _a !== void 0 ? _a : Date.now;
+        const random = (_b = input.random) !== null && _b !== void 0 ? _b : Math.random;
+        const sleep = (_c = input.sleep) !== null && _c !== void 0 ? _c : ((milliseconds) => new Promise((resolve) => {
+            setTimeout(resolve, milliseconds);
+        }));
+        const startedAt = now();
+        let lastErrorCode = 'retry-budget-exhausted';
+        let attempts = 0;
+        for (let attempt = 1; attempt <= policy.maximumAttempts; attempt += 1) {
+            const elapsed = Math.max(0, now() - startedAt);
+            const remaining = policy.totalTimeoutMs - elapsed;
+            if (remaining <= 0)
+                break;
+            attempts = attempt;
+            const result = yield timedAttempt(input.attempt, attempt, Math.min(policy.attemptTimeoutMs, remaining));
+            if (result.outcome === 'succeeded') {
+                return { attempts: attempt, outcome: 'succeeded', value: result.value };
+            }
+            lastErrorCode = requireAsyncIdentifier(result.errorCode, `/attempts/${attempt - 1}/errorCode`);
+            if (result.outcome === 'terminal') {
+                return {
+                    attempts: attempt,
+                    errorCode: lastErrorCode,
+                    outcome: 'terminal',
+                };
+            }
+            if (attempt === policy.maximumAttempts)
+                break;
+            const cap = Math.min(policy.maximumDelayMs, policy.baseDelayMs * Math.pow(2, (attempt - 1)));
+            const randomValue = requireAsyncNumber(random(), '/random', 0, 1);
+            const delay = Math.floor(cap * randomValue);
+            const remainingAfterAttempt = policy.totalTimeoutMs - (now() - startedAt);
+            if (delay >= remainingAfterAttempt)
+                break;
+            yield sleep(delay);
+        }
+        return {
+            attempts,
+            errorCode: lastErrorCode,
+            outcome: 'retry-exhausted',
+        };
+    });
+}
+/**
+ * Produces AWS Lambda's partial-batch response without ever returning message
+ * bodies. Terminal records remain failed so SQS moves them through the
+ * declared receive count to the DLQ instead of silently dropping them.
+ */
+export function processSqsBatch(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!Array.isArray(input.records) || input.records.length > 10) {
+            failAsyncWork('async-input-invalid', '/records', 'must contain at most ten SQS records');
+        }
+        const seen = new Set();
+        const failures = [];
+        let succeeded = 0;
+        for (const [index, record] of input.records.entries()) {
+            const messageId = requireAsyncIdentifier(record === null || record === void 0 ? void 0 : record.messageId, `/records/${index}/messageId`);
+            if (seen.has(messageId)) {
+                failAsyncWork('async-input-invalid', `/records/${index}/messageId`, 'must be unique inside one Lambda batch');
+            }
+            seen.add(messageId);
+            let outcome;
+            try {
+                outcome = yield input.handler(record);
+            }
+            catch (_a) {
+                outcome = { errorCode: 'unhandled-handler-error', outcome: 'retry' };
+            }
+            if ((outcome === null || outcome === void 0 ? void 0 : outcome.outcome) === 'succeeded') {
+                succeeded += 1;
+                continue;
+            }
+            if (!outcome ||
+                !['retry', 'terminal'].includes(outcome.outcome) ||
+                typeof outcome.errorCode !== 'string') {
+                failAsyncWork('async-adapter-outcome-invalid', `/records/${index}/outcome`, 'handler must return succeeded, retry, or terminal');
+            }
+            failures.push({
+                errorCode: requireAsyncIdentifier(outcome.errorCode, `/records/${index}/outcome/errorCode`),
+                messageId,
+                outcome: outcome.outcome,
+            });
+        }
+        return {
+            failed: failures.length,
+            failureMetadata: failures,
+            response: {
+                batchItemFailures: failures.map(({ messageId }) => ({
+                    itemIdentifier: messageId,
+                })),
+            },
+            succeeded,
+            total: input.records.length,
+        };
+    });
+}
+function normalizeDlqScope(scope) {
+    const receivedAfter = scope.receivedAfter === undefined
+        ? undefined
+        : requireCanonicalAsyncTimestamp(scope.receivedAfter, '/scope/receivedAfter');
+    const receivedBefore = scope.receivedBefore === undefined
+        ? undefined
+        : requireCanonicalAsyncTimestamp(scope.receivedBefore, '/scope/receivedBefore');
+    if (receivedAfter &&
+        receivedBefore &&
+        Date.parse(receivedAfter) >= Date.parse(receivedBefore)) {
+        failAsyncWork('async-input-invalid', '/scope', 'receivedAfter must precede receivedBefore');
+    }
+    if (!Array.isArray(scope.workTypes) || scope.workTypes.length === 0) {
+        failAsyncWork('async-input-invalid', '/scope/workTypes', 'must explicitly name at least one work type');
+    }
+    const workTypes = scope.workTypes
+        .map((value, index) => requireAsyncIdentifier(value, `/scope/workTypes/${index}`))
+        .sort(compareAsyncStrings);
+    if (new Set(workTypes).size !== workTypes.length) {
+        failAsyncWork('async-input-invalid', '/scope/workTypes', 'must not contain duplicates');
+    }
+    return Object.assign(Object.assign(Object.assign({ maximumMessages: requireAsyncInteger(scope.maximumMessages, '/scope/maximumMessages', 1, 10000) }, (receivedAfter ? { receivedAfter } : {})), (receivedBefore ? { receivedBefore } : {})), { workTypes });
+}
+export function createDlqRedriveReport(input) {
+    const preparedAt = requireCanonicalAsyncTimestamp(input.preparedAt, '/preparedAt');
+    const expiresAt = requireCanonicalAsyncTimestamp(input.expiresAt, '/expiresAt');
+    if (Date.parse(expiresAt) <= Date.parse(preparedAt)) {
+        failAsyncWork('async-input-invalid', '/expiresAt', 'must be later than preparedAt');
+    }
+    if (!['ordinary', 'protected'].includes(input.approvalClass)) {
+        failAsyncWork('async-input-invalid', '/approvalClass', 'must be ordinary or protected');
+    }
+    const scope = normalizeDlqScope(input.scope);
+    if (!Array.isArray(input.messages) || input.messages.length > 100000) {
+        failAsyncWork('async-input-invalid', '/messages', 'must contain at most 100000 metadata records');
+    }
+    const allowedTypes = new Set(scope.workTypes);
+    const selected = input.messages
+        .map((message, index) => ({
+        messageId: requireAsyncIdentifier(message.messageId, `/messages/${index}/messageId`),
+        receivedAt: requireCanonicalAsyncTimestamp(message.receivedAt, `/messages/${index}/receivedAt`),
+        receiveCount: requireAsyncInteger(message.receiveCount, `/messages/${index}/receiveCount`, 1, 1000000),
+        workType: requireAsyncIdentifier(message.workType, `/messages/${index}/workType`),
+    }))
+        .filter((message) => allowedTypes.has(message.workType) &&
+        (!scope.receivedAfter ||
+            Date.parse(message.receivedAt) >= Date.parse(scope.receivedAfter)) &&
+        (!scope.receivedBefore ||
+            Date.parse(message.receivedAt) < Date.parse(scope.receivedBefore)))
+        .sort((left, right) => {
+        const time = compareAsyncStrings(left.receivedAt, right.receivedAt);
+        return time || compareAsyncStrings(left.messageId, right.messageId);
+    })
+        .slice(0, scope.maximumMessages);
+    const messageIds = selected.map(({ messageId }) => messageId);
+    if (new Set(messageIds).size !== messageIds.length) {
+        failAsyncWork('async-input-invalid', '/messages', 'must not contain duplicate message IDs');
+    }
+    const material = {
+        approvalClass: input.approvalClass,
+        expiresAt,
+        messageIds,
+        preparedAt,
+        queue: requireAsyncIdentifier(input.queue, '/queue'),
+        ratePerSecond: requireAsyncNumber(input.ratePerSecond, '/ratePerSecond', 0.01, 10000),
+        scope,
+        selectedCount: selected.length,
+        version: 1,
+    };
+    const reportDigest = asyncWorkDigest(material);
+    return Object.assign(Object.assign({}, material), { reportDigest, reportId: asyncWorkDigest({
+            operation: 'dlq-redrive-v1',
+            reportDigest,
+        }) });
+}
+export function applyDlqRedrive(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const now = requireCanonicalAsyncTimestamp(input.now, '/now');
+        const report = input.report;
+        const { reportDigest: ignoredDigest, reportId: ignoredId } = report, material = __rest(report, ["reportDigest", "reportId"]);
+        void ignoredDigest;
+        void ignoredId;
+        const expectedDigest = asyncWorkDigest(material);
+        if (report.version !== 1 ||
+            report.reportDigest !== expectedDigest ||
+            report.reportId !==
+                asyncWorkDigest({
+                    operation: 'dlq-redrive-v1',
+                    reportDigest: expectedDigest,
+                })) {
+            failAsyncWork('async-report-invalid', '/report', 'digest does not bind the exact redrive scope');
+        }
+        if (Date.parse(now) >= Date.parse(report.expiresAt)) {
+            failAsyncWork('async-report-expired', '/report/expiresAt', 'report expired');
+        }
+        if (report.approvalClass === 'protected' &&
+            (input.approvalId === undefined ||
+                !requireAsyncIdentifier(input.approvalId, '/approvalId'))) {
+            failAsyncWork('async-approval-required', '/approvalId', 'protected redrive requires an attributable approval');
+        }
+        const available = new Set(input.availableMessageIds.map((value, index) => requireAsyncIdentifier(value, `/availableMessageIds/${index}`)));
+        const pending = report.messageIds.filter((messageId) => available.has(messageId));
+        if (pending.length === 0) {
+            return {
+                acceptedCount: 0,
+                operationId: report.reportId,
+                outcome: 'converged',
+                remainingCount: 0,
+            };
+        }
+        const result = yield input.adapter.redrive({
+            messageIds: pending,
+            operationId: report.reportId,
+            ratePerSecond: report.ratePerSecond,
+        });
+        const accepted = new Set(result.acceptedMessageIds.map((value, index) => requireAsyncIdentifier(value, `/adapter/acceptedMessageIds/${index}`)));
+        if (accepted.size !== result.acceptedMessageIds.length) {
+            failAsyncWork('async-adapter-outcome-invalid', '/adapter/acceptedMessageIds', 'adapter returned duplicate accepted message IDs');
+        }
+        for (const messageId of accepted) {
+            if (!pending.includes(messageId)) {
+                failAsyncWork('async-adapter-outcome-invalid', '/adapter/acceptedMessageIds', 'adapter accepted a message outside the approved report');
+            }
+        }
+        return {
+            acceptedCount: accepted.size,
+            operationId: report.reportId,
+            outcome: 'applied',
+            remainingCount: pending.length - accepted.size,
+        };
+    });
+}
+//# sourceMappingURL=sqs.js.map

package/src/async-work/sqs.js.map

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

package/src/async-work/webhook.d.ts

@@ -0,0 +1,60 @@
+export declare const ASYNC_WEBHOOK_RECEIPT_VERSION: 1;
+export interface WebhookSigningKey {
+    keyId: string;
+    notAfter?: string;
+    notBefore: string;
+    secret: string | Uint8Array;
+}
+export interface VerifiedWebhookV1 {
+    account: string;
+    endpoint: string;
+    keyId: string;
+    payloadDigest: string;
+    provider: string;
+    signedAt: string;
+    version: 1;
+}
+/**
+ * Provider adapters can use this helper in fixtures and outbound webhook
+ * delivery. The signed material binds timestamp, endpoint, account, and the
+ * exact raw bytes.
+ */
+export declare function signWebhookRequest(input: {
+    account: string;
+    endpoint: string;
+    keyId: string;
+    rawBody: Uint8Array;
+    secret: string | Uint8Array;
+    timestampSeconds: number;
+}): string;
+export declare function verifySignedWebhook(input: {
+    account: string;
+    endpoint: string;
+    keys: readonly WebhookSigningKey[];
+    maximumBodyBytes: number;
+    now: string;
+    provider: string;
+    rawBody: Uint8Array;
+    signatureHeader: string;
+    toleranceSeconds: number;
+}): VerifiedWebhookV1;
+export interface WebhookReceiptV1 {
+    account: string;
+    endpoint: string;
+    idempotencyKey: string;
+    payloadDigest: string;
+    provider: string;
+    providerEventId: string;
+    receivedAt: string;
+    version: typeof ASYNC_WEBHOOK_RECEIPT_VERSION;
+}
+/**
+ * The receipt intentionally contains no request body or parsed provider
+ * payload. The provider event ID plus payload digest makes a changed replay a
+ * conflict instead of silently treating it as a duplicate.
+ */
+export declare function createWebhookReceipt(input: {
+    providerEventId: string;
+    receivedAt: string;
+    verified: VerifiedWebhookV1;
+}): WebhookReceiptV1;

package/src/async-work/webhook.js

@@ -0,0 +1,178 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { asyncWorkDigest, asyncWorkIdentity, failAsyncWork, requireAsyncIdentifier, requireAsyncInteger, requireCanonicalAsyncTimestamp, } from './contract.js';
+export const ASYNC_WEBHOOK_RECEIPT_VERSION = 1;
+function requireWebhookSecret(value, pointer) {
+    const length = typeof value === 'string'
+        ? Buffer.byteLength(value, 'utf8')
+        : value instanceof Uint8Array
+            ? value.byteLength
+            : 0;
+    if (length < 16 || length > 4096) {
+        failAsyncWork('async-input-invalid', pointer, 'must contain from 16 through 4096 secret bytes');
+    }
+    return value;
+}
+function signaturePayload(input) {
+    const prefix = Buffer.from(`${input.timestampSeconds}.${input.endpoint}.${input.account}.`, 'utf8');
+    return Buffer.concat([prefix, Buffer.from(input.rawBody)]);
+}
+function hmac(input) {
+    return createHmac('sha256', input.secret)
+        .update(signaturePayload(input))
+        .digest();
+}
+/**
+ * Provider adapters can use this helper in fixtures and outbound webhook
+ * delivery. The signed material binds timestamp, endpoint, account, and the
+ * exact raw bytes.
+ */
+export function signWebhookRequest(input) {
+    const account = requireAsyncIdentifier(input.account, '/account');
+    const endpoint = requireAsyncIdentifier(input.endpoint, '/endpoint');
+    const keyId = requireAsyncIdentifier(input.keyId, '/keyId');
+    const timestampSeconds = requireAsyncInteger(input.timestampSeconds, '/timestampSeconds', 1, Number.MAX_SAFE_INTEGER);
+    if (!(input.rawBody instanceof Uint8Array)) {
+        failAsyncWork('async-input-invalid', '/rawBody', 'must be the exact request bytes');
+    }
+    const secret = requireWebhookSecret(input.secret, '/secret');
+    return `t=${timestampSeconds},k=${keyId},v1=${hmac({
+        account,
+        endpoint,
+        rawBody: input.rawBody,
+        secret,
+        timestampSeconds,
+    }).toString('hex')}`;
+}
+function parseSignatureHeader(value) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > 1024 ||
+        /[\r\n]/.test(value)) {
+        failAsyncWork('async-webhook-signature-invalid', '/signatureHeader', 'must be a bounded single-line signature');
+    }
+    const fields = new Map();
+    for (const field of value.split(',')) {
+        const separator = field.indexOf('=');
+        if (separator < 1) {
+            failAsyncWork('async-webhook-signature-invalid', '/signatureHeader', 'contains a malformed field');
+        }
+        const name = field.slice(0, separator);
+        const item = field.slice(separator + 1);
+        if (fields.has(name) || !['k', 't', 'v1'].includes(name)) {
+            failAsyncWork('async-webhook-signature-invalid', '/signatureHeader', 'contains duplicate or unsupported fields');
+        }
+        fields.set(name, item);
+    }
+    const timestampText = fields.get('t');
+    const signatureText = fields.get('v1');
+    const keyId = fields.get('k');
+    if (!timestampText ||
+        !/^[1-9]\d{0,15}$/.test(timestampText) ||
+        !signatureText ||
+        !/^[a-f0-9]{64}$/.test(signatureText) ||
+        !keyId) {
+        failAsyncWork('async-webhook-signature-invalid', '/signatureHeader', 'must contain t, k, and one sha256 v1 signature');
+    }
+    return {
+        keyId: requireAsyncIdentifier(keyId, '/signatureHeader/k'),
+        signature: Buffer.from(signatureText, 'hex'),
+        timestampSeconds: Number(timestampText),
+    };
+}
+export function verifySignedWebhook(input) {
+    const now = requireCanonicalAsyncTimestamp(input.now, '/now');
+    const account = requireAsyncIdentifier(input.account, '/account');
+    const endpoint = requireAsyncIdentifier(input.endpoint, '/endpoint');
+    const provider = requireAsyncIdentifier(input.provider, '/provider');
+    const maximumBodyBytes = requireAsyncInteger(input.maximumBodyBytes, '/maximumBodyBytes', 1, 10 * 1024 * 1024);
+    const toleranceSeconds = requireAsyncInteger(input.toleranceSeconds, '/toleranceSeconds', 1, 86400);
+    if (!(input.rawBody instanceof Uint8Array) ||
+        input.rawBody.byteLength > maximumBodyBytes) {
+        failAsyncWork('async-input-invalid', '/rawBody', `must be exact request bytes no larger than ${maximumBodyBytes}`);
+    }
+    if (!Array.isArray(input.keys) ||
+        input.keys.length < 1 ||
+        input.keys.length > 2) {
+        failAsyncWork('async-input-invalid', '/keys', 'must contain the active key and at most one bounded overlap key');
+    }
+    const parsed = parseSignatureHeader(input.signatureHeader);
+    const signedAtMs = parsed.timestampSeconds * 1000;
+    if (Math.abs(Date.parse(now) - signedAtMs) > toleranceSeconds * 1000) {
+        failAsyncWork('async-webhook-timestamp-invalid', '/signatureHeader/t', 'is outside the accepted replay tolerance');
+    }
+    const keys = input.keys.map((candidate, index) => {
+        const notBefore = requireCanonicalAsyncTimestamp(candidate.notBefore, `/keys/${index}/notBefore`);
+        const notAfter = candidate.notAfter === undefined
+            ? undefined
+            : requireCanonicalAsyncTimestamp(candidate.notAfter, `/keys/${index}/notAfter`);
+        if (index > 0 && notAfter === undefined) {
+            failAsyncWork('async-input-invalid', `/keys/${index}/notAfter`, 'an overlap key must have a bounded revocation time');
+        }
+        if (notAfter !== undefined &&
+            Date.parse(notAfter) <= Date.parse(notBefore)) {
+            failAsyncWork('async-input-invalid', `/keys/${index}/notAfter`, 'must be later than notBefore');
+        }
+        return Object.assign(Object.assign({ keyId: requireAsyncIdentifier(candidate.keyId, `/keys/${index}/keyId`) }, (notAfter ? { notAfter } : {})), { notBefore, secret: requireWebhookSecret(candidate.secret, `/keys/${index}/secret`) });
+    });
+    if (new Set(keys.map(({ keyId }) => keyId)).size !== keys.length) {
+        failAsyncWork('async-input-invalid', '/keys', 'must not contain duplicate key IDs');
+    }
+    const keyIndex = keys.findIndex((candidate) => candidate.keyId === parsed.keyId);
+    if (keyIndex < 0) {
+        failAsyncWork('async-webhook-signature-invalid', '/signatureHeader/k', 'does not select an accepted key');
+    }
+    const key = keys[keyIndex];
+    const { notAfter, notBefore } = key;
+    if (signedAtMs < Date.parse(notBefore) ||
+        (notAfter !== undefined && signedAtMs >= Date.parse(notAfter))) {
+        failAsyncWork('async-webhook-signature-invalid', `/keys/${keyIndex}`, 'was not valid when the request was signed');
+    }
+    const expected = hmac({
+        account,
+        endpoint,
+        rawBody: input.rawBody,
+        secret: key.secret,
+        timestampSeconds: parsed.timestampSeconds,
+    });
+    if (expected.length !== parsed.signature.length ||
+        !timingSafeEqual(expected, parsed.signature)) {
+        failAsyncWork('async-webhook-signature-invalid', '/signatureHeader/v1', 'does not authenticate the exact raw request bytes and endpoint context');
+    }
+    return {
+        account,
+        endpoint,
+        keyId: parsed.keyId,
+        payloadDigest: asyncWorkDigest(Array.from(input.rawBody)),
+        provider,
+        signedAt: new Date(signedAtMs).toISOString(),
+        version: 1,
+    };
+}
+/**
+ * The receipt intentionally contains no request body or parsed provider
+ * payload. The provider event ID plus payload digest makes a changed replay a
+ * conflict instead of silently treating it as a duplicate.
+ */
+export function createWebhookReceipt(input) {
+    var _a;
+    if (((_a = input.verified) === null || _a === void 0 ? void 0 : _a.version) !== 1) {
+        failAsyncWork('async-input-invalid', '/verified', 'must be a verified v1 webhook');
+    }
+    const providerEventId = requireAsyncIdentifier(input.providerEventId, '/providerEventId');
+    const receivedAt = requireCanonicalAsyncTimestamp(input.receivedAt, '/receivedAt');
+    return {
+        account: input.verified.account,
+        endpoint: input.verified.endpoint,
+        idempotencyKey: asyncWorkIdentity('webhook-receipt-v1', [
+            input.verified.provider,
+            input.verified.account,
+            providerEventId,
+        ]),
+        payloadDigest: input.verified.payloadDigest,
+        provider: input.verified.provider,
+        providerEventId,
+        receivedAt,
+        version: ASYNC_WEBHOOK_RECEIPT_VERSION,
+    };
+}
+//# sourceMappingURL=webhook.js.map

package/src/async-work/webhook.js.map

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

package/src/async-work/workflow.d.ts

@@ -0,0 +1,98 @@
+export declare const ASYNC_WORKFLOW_DEFINITION_VERSION: 1;
+export declare const ASYNC_WORKFLOW_CALLBACK_VERSION: 1;
+export interface WorkflowStepV1 {
+    compensationStepId?: string;
+    estimatedCostUsd: number;
+    maximumAttempts: number;
+    stepId: string;
+    timeoutSeconds: number;
+}
+export interface WorkflowDefinitionV1 {
+    dataClassification: string;
+    estimatedFailureCostUsd: number;
+    estimatedNormalCostUsd: number;
+    inputContract: string;
+    retentionDays: number;
+    steps: readonly WorkflowStepV1[];
+    version: typeof ASYNC_WORKFLOW_DEFINITION_VERSION;
+    workflow: string;
+    workflowVersion: number;
+}
+export declare function createWorkflowDefinition(input: Omit<WorkflowDefinitionV1, 'version'>): WorkflowDefinitionV1;
+/**
+ * In-flight executions always resolve their recorded workflow version. A new
+ * deployment cannot silently reinterpret old state using the newest handler.
+ */
+export declare function selectWorkflowVersion(input: {
+    definitions: readonly WorkflowDefinitionV1[];
+    execution: {
+        workflow: string;
+        workflowVersion: number;
+    };
+}): WorkflowDefinitionV1;
+export interface WorkflowCallbackClaimsV1 {
+    callbackId: string;
+    executionId: string;
+    expiresAt: string;
+    nonce: string;
+    version: typeof ASYNC_WORKFLOW_CALLBACK_VERSION;
+    workflow: string;
+    workflowVersion: number;
+}
+export declare function createWorkflowCallbackToken(input: {
+    claims: Omit<WorkflowCallbackClaimsV1, 'version'>;
+    secret: string | Uint8Array;
+}): string;
+export declare function verifyWorkflowCallbackToken(input: {
+    expected: {
+        callbackId: string;
+        executionId: string;
+        workflow: string;
+        workflowVersion: number;
+    };
+    now: string;
+    secret: string | Uint8Array;
+    token: string;
+}): {
+    callbackClaimKey: string;
+    claims: WorkflowCallbackClaimsV1;
+    tokenDigest: string;
+};
+export type WorkflowExecutionStatus = 'cancelled' | 'cancellation-requested' | 'failed' | 'running' | 'succeeded' | 'waiting';
+export interface WorkflowCancellationV1 {
+    actor: string;
+    executionId: string;
+    reason: string;
+    requestedAt: string;
+    status: 'cancellation-requested';
+    workflow: string;
+}
+export declare function requestWorkflowCancellation(input: {
+    actor: string;
+    executionId: string;
+    reason: string;
+    requestedAt: string;
+    status: WorkflowExecutionStatus;
+    workflow: string;
+}): WorkflowCancellationV1;
+export interface WorkflowCompensationActionV1 {
+    compensationStepId: string;
+    idempotencyKey: string;
+    originalStepId: string;
+}
+export declare function createCompensationPlan(input: {
+    authorizationId: string;
+    completedStepIds: readonly string[];
+    definition: WorkflowDefinitionV1;
+    executionId: string;
+    reason: string;
+}): {
+    actions: readonly WorkflowCompensationActionV1[];
+    authorizationId: string;
+    executionId: string;
+    planDigest: string;
+    reason: string;
+    workflow: string;
+    workflowVersion: number;
+};
+export declare function workflowDefinitionDigest(definition: WorkflowDefinitionV1): string;