deepline 0.3.113 → 0.3.115

package/dist/bundling-sources/shared_libs/play-runtime/fixture-behavior.ts

@@ -456,6 +456,7 @@ export function isReplaySafeFixtureToolId(toolId: string): boolean {
   return (
     shouldRouteFixtureToolId(normalized) &&
     normalized !== 'ai_inference' &&
+    normalized !== 'ai_evaluate' &&
     normalized !== 'deeplineagent' &&
     !normalized.startsWith('deeplineagent_')
   );

package/dist/bundling-sources/shared_libs/play-runtime/internal-bootstrap-token.ts

@@ -10,6 +10,13 @@ import {
   type FixtureBehavior,
 } from './/fixture-behavior';
 import { normalizeRuntimeSchedulerSchema } from './/runtime-scheduler-topology';
+import {
+  mintPlayWebhookReceiptLargeBatchAdmissionToken as mintPlayWebhookReceiptLargeBatchAdmissionTokenShared,
+  mintPlayTriggerEventAdmissionToken as mintPlayTriggerEventAdmissionTokenShared,
+  mintPlayWebhookReceiptBatchAdmissionToken as mintPlayWebhookReceiptBatchAdmissionTokenShared,
+  mintPlayWebhookReceiptAdmissionToken as mintPlayWebhookReceiptAdmissionTokenShared,
+  mintSignalRadarInboundReceiptToken as mintSignalRadarInboundReceiptTokenShared,
+} from '../security/receipt-admission-token';
 import { SignJWT, exportJWK, importJWK, jwtVerify, type JWK } from 'jose';
 import {
   directCompletedTerminalContract,
@@ -79,6 +86,24 @@ const PRODUCT_NOTIFICATION_DELIVERY_AUDIENCE =
   'deepline.product_notification.delivery' as const;
 const PRODUCT_NOTIFICATION_DELIVERY_PURPOSE =
   'product_notification_delivery' as const;
+const PLAY_WEBHOOK_RECEIPT_ADMISSION_AUDIENCE =
+  'deepline.play_webhook_receipt.admission' as const;
+const PLAY_WEBHOOK_RECEIPT_ADMISSION_PURPOSE =
+  'play_webhook_receipt_admission' as const;
+const PLAY_WEBHOOK_RECEIPT_BATCH_ADMISSION_AUDIENCE =
+  'deepline.play_webhook_receipt.batch_admission' as const;
+const PLAY_WEBHOOK_RECEIPT_BATCH_ADMISSION_PURPOSE =
+  'play_webhook_receipt_batch_admission' as const;
+const PLAY_WEBHOOK_RECEIPT_LARGE_BATCH_ADMISSION_PURPOSE =
+  'play_webhook_receipt_large_batch_admission' as const;
+const PLAY_TRIGGER_EVENT_ADMISSION_AUDIENCE =
+  'deepline.play_trigger_event.admission' as const;
+const PLAY_TRIGGER_EVENT_ADMISSION_PURPOSE =
+  'play_trigger_event_admission' as const;
+const SIGNAL_RADAR_INBOUND_RECEIPT_AUDIENCE =
+  'deepline.signal_radar_inbound_receipt.process' as const;
+const SIGNAL_RADAR_INBOUND_RECEIPT_PURPOSE =
+  'signal_radar_inbound_receipt_process' as const;
 const PRODUCT_NOTIFICATION_UNSUBSCRIBE_AUDIENCE =
   'deepline.product_notification.unsubscribe' as const;
 const PRODUCT_NOTIFICATION_UNSUBSCRIBE_PURPOSE =
@@ -146,6 +171,67 @@ export type ProductNotificationDeliveryTokenClaims = {
   v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
 };
 
+/** Capability for exactly one Convex-owned webhook receipt admission. */
+export type PlayWebhookReceiptAdmissionTokenClaims = {
+  aud: typeof PLAY_WEBHOOK_RECEIPT_ADMISSION_AUDIENCE;
+  exp: number;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  org_id: string;
+  purpose: typeof PLAY_WEBHOOK_RECEIPT_ADMISSION_PURPOSE;
+  receipt_id: string;
+  sub: 'play_webhook_receipt_dispatcher';
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
+/** Capability for a bounded, single-workspace collection of receipt IDs. */
+type PlayWebhookReceiptBatchAdmissionTokenBaseClaims = {
+  aud: typeof PLAY_WEBHOOK_RECEIPT_BATCH_ADMISSION_AUDIENCE;
+  exp: number;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  org_id: string;
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
+export type PlayWebhookReceiptBatchAdmissionTokenClaims =
+  | (PlayWebhookReceiptBatchAdmissionTokenBaseClaims & {
+      purpose: typeof PLAY_WEBHOOK_RECEIPT_BATCH_ADMISSION_PURPOSE;
+      receipt_ids: string[];
+      sub: 'play_webhook_receipt_batch_dispatcher';
+    })
+  | (PlayWebhookReceiptBatchAdmissionTokenBaseClaims & {
+      purpose: typeof PLAY_WEBHOOK_RECEIPT_LARGE_BATCH_ADMISSION_PURPOSE;
+      receipt_ids_sha256: string;
+      sub: 'play_webhook_receipt_large_batch_dispatcher';
+    });
+
+/** Capability for exactly one Convex-owned cron trigger-event admission. */
+export type PlayTriggerEventAdmissionTokenClaims = {
+  aud: typeof PLAY_TRIGGER_EVENT_ADMISSION_AUDIENCE;
+  event_id: string;
+  exp: number;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  org_id: string;
+  purpose: typeof PLAY_TRIGGER_EVENT_ADMISSION_PURPOSE;
+  sub: 'play_trigger_event_dispatcher';
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
+/** Capability for one Convex-owned monitor inbound receipt processor call. */
+export type SignalRadarInboundReceiptTokenClaims = {
+  aud: typeof SIGNAL_RADAR_INBOUND_RECEIPT_AUDIENCE;
+  exp: number;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  org_id: string;
+  purpose: typeof SIGNAL_RADAR_INBOUND_RECEIPT_PURPOSE;
+  receipt_id: string;
+  sub: 'signal_radar_inbound_receipt_dispatcher';
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
 export type ProductNotificationUnsubscribeTokenClaims = {
   aud: typeof PRODUCT_NOTIFICATION_UNSUBSCRIBE_AUDIENCE;
   group_key: string;
@@ -1045,6 +1131,245 @@ export async function verifyProductNotificationDeliveryToken(
   return claims as ProductNotificationDeliveryTokenClaims;
 }
 
+export async function mintPlayWebhookReceiptAdmissionToken(input: {
+  orgId: string;
+  receiptId: string;
+  nowMs?: number;
+}): Promise<string> {
+  return await mintPlayWebhookReceiptAdmissionTokenShared(input);
+}
+
+export async function mintPlayWebhookReceiptBatchAdmissionToken(input: {
+  orgId: string;
+  receiptIds: readonly string[];
+  nowMs?: number;
+}): Promise<string> {
+  return await mintPlayWebhookReceiptBatchAdmissionTokenShared(input);
+}
+
+export async function mintPlayWebhookReceiptLargeBatchAdmissionToken(input: {
+  orgId: string;
+  receiptIds: readonly string[];
+  nowMs?: number;
+}): Promise<string> {
+  return await mintPlayWebhookReceiptLargeBatchAdmissionTokenShared(input);
+}
+
+export async function verifyPlayWebhookReceiptBatchAdmissionToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<PlayWebhookReceiptBatchAdmissionTokenClaims> {
+  const segments = token.split('.');
+  if (segments.length !== 3)
+    throw new Error('Invalid webhook receipt batch token.');
+  const [encodedHeader, encodedClaims, signature] = segments;
+  const header = decodeJson<Record<string, unknown>>(encodedHeader);
+  if (header.alg !== 'HS256' || header.typ !== 'JWT') {
+    throw new Error('Invalid webhook receipt batch token.');
+  }
+  const expectedSignature = await signTokenMaterial(
+    `${encodedHeader}.${encodedClaims}`,
+  );
+  if (
+    !timingSafeEqual(fromBase64Url(signature), fromBase64Url(expectedSignature))
+  ) {
+    throw new Error('Invalid webhook receipt batch token.');
+  }
+  const claims = decodeJson<Record<string, unknown>>(encodedClaims);
+  const hasInvalidBaseClaims =
+    claims.v !== INTERNAL_BOOTSTRAP_TOKEN_VERSION ||
+    claims.iss !== INTERNAL_BOOTSTRAP_TOKEN_ISSUER ||
+    claims.aud !== PLAY_WEBHOOK_RECEIPT_BATCH_ADMISSION_AUDIENCE ||
+    typeof claims.org_id !== 'string' ||
+    claims.org_id.length === 0 ||
+    typeof claims.iat !== 'number' ||
+    !Number.isFinite(claims.iat) ||
+    typeof claims.exp !== 'number' ||
+    !Number.isFinite(claims.exp);
+  const hasValidV1Claims =
+    claims.purpose === PLAY_WEBHOOK_RECEIPT_BATCH_ADMISSION_PURPOSE &&
+    claims.sub === 'play_webhook_receipt_batch_dispatcher' &&
+    Array.isArray(claims.receipt_ids) &&
+    claims.receipt_ids.length >= 1 &&
+    claims.receipt_ids.length <= 32 &&
+    !claims.receipt_ids.some(
+      (receiptId) => typeof receiptId !== 'string' || receiptId.length === 0,
+    ) &&
+    new Set(claims.receipt_ids).size === claims.receipt_ids.length;
+  const hasValidV2Claims =
+    claims.purpose === PLAY_WEBHOOK_RECEIPT_LARGE_BATCH_ADMISSION_PURPOSE &&
+    claims.sub === 'play_webhook_receipt_large_batch_dispatcher' &&
+    typeof claims.receipt_ids_sha256 === 'string' &&
+    /^[A-Za-z0-9_-]{43}$/.test(claims.receipt_ids_sha256);
+  if (
+    hasInvalidBaseClaims ||
+    (!hasValidV1Claims && !hasValidV2Claims)
+  ) {
+    throw new Error('Invalid webhook receipt batch token.');
+  }
+  // `hasInvalidBaseClaims` is deliberately a named diagnostic, but TypeScript
+  // cannot narrow `Record<string, unknown>` through that boolean. Reassert the
+  // already-validated temporal claim types before comparing them below.
+  const expiresAt = claims.exp;
+  const issuedAt = claims.iat;
+  if (typeof expiresAt !== 'number' || typeof issuedAt !== 'number') {
+    throw new Error('Invalid webhook receipt batch token.');
+  }
+  const nowSeconds = Math.floor(nowMs / 1000);
+  if (expiresAt <= nowSeconds || issuedAt > nowSeconds + 30) {
+    throw new Error('Webhook receipt batch token expired.');
+  }
+  return claims as PlayWebhookReceiptBatchAdmissionTokenClaims;
+}
+
+export async function verifyPlayWebhookReceiptAdmissionToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<PlayWebhookReceiptAdmissionTokenClaims> {
+  const segments = token.split('.');
+  if (segments.length !== 3) throw new Error('Invalid webhook receipt token.');
+  const [encodedHeader, encodedClaims, signature] = segments;
+  const header = decodeJson<Record<string, unknown>>(encodedHeader);
+  if (header.alg !== 'HS256' || header.typ !== 'JWT') {
+    throw new Error('Invalid webhook receipt token.');
+  }
+  const expectedSignature = await signTokenMaterial(
+    `${encodedHeader}.${encodedClaims}`,
+  );
+  if (
+    !timingSafeEqual(fromBase64Url(signature), fromBase64Url(expectedSignature))
+  ) {
+    throw new Error('Invalid webhook receipt token.');
+  }
+  const claims = decodeJson<Record<string, unknown>>(encodedClaims);
+  if (
+    claims.v !== INTERNAL_BOOTSTRAP_TOKEN_VERSION ||
+    claims.iss !== INTERNAL_BOOTSTRAP_TOKEN_ISSUER ||
+    claims.aud !== PLAY_WEBHOOK_RECEIPT_ADMISSION_AUDIENCE ||
+    claims.purpose !== PLAY_WEBHOOK_RECEIPT_ADMISSION_PURPOSE ||
+    claims.sub !== 'play_webhook_receipt_dispatcher' ||
+    typeof claims.org_id !== 'string' ||
+    claims.org_id.length === 0 ||
+    typeof claims.receipt_id !== 'string' ||
+    claims.receipt_id.length === 0 ||
+    typeof claims.iat !== 'number' ||
+    !Number.isFinite(claims.iat) ||
+    typeof claims.exp !== 'number' ||
+    !Number.isFinite(claims.exp)
+  ) {
+    throw new Error('Invalid webhook receipt token.');
+  }
+  const nowSeconds = Math.floor(nowMs / 1000);
+  if (claims.exp <= nowSeconds || claims.iat > nowSeconds + 30) {
+    throw new Error('Webhook receipt token expired.');
+  }
+  return claims as PlayWebhookReceiptAdmissionTokenClaims;
+}
+
+export async function mintPlayTriggerEventAdmissionToken(input: {
+  orgId: string;
+  eventId: string;
+  nowMs?: number;
+}): Promise<string> {
+  return await mintPlayTriggerEventAdmissionTokenShared(input);
+}
+
+export async function verifyPlayTriggerEventAdmissionToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<PlayTriggerEventAdmissionTokenClaims> {
+  const segments = token.split('.');
+  if (segments.length !== 3) throw new Error('Invalid trigger event token.');
+  const [encodedHeader, encodedClaims, signature] = segments;
+  const header = decodeJson<Record<string, unknown>>(encodedHeader);
+  if (header.alg !== 'HS256' || header.typ !== 'JWT') {
+    throw new Error('Invalid trigger event token.');
+  }
+  const expectedSignature = await signTokenMaterial(
+    `${encodedHeader}.${encodedClaims}`,
+  );
+  if (
+    !timingSafeEqual(fromBase64Url(signature), fromBase64Url(expectedSignature))
+  ) {
+    throw new Error('Invalid trigger event token.');
+  }
+  const claims = decodeJson<Record<string, unknown>>(encodedClaims);
+  if (
+    claims.v !== INTERNAL_BOOTSTRAP_TOKEN_VERSION ||
+    claims.iss !== INTERNAL_BOOTSTRAP_TOKEN_ISSUER ||
+    claims.aud !== PLAY_TRIGGER_EVENT_ADMISSION_AUDIENCE ||
+    claims.purpose !== PLAY_TRIGGER_EVENT_ADMISSION_PURPOSE ||
+    claims.sub !== 'play_trigger_event_dispatcher' ||
+    typeof claims.org_id !== 'string' ||
+    claims.org_id.length === 0 ||
+    typeof claims.event_id !== 'string' ||
+    claims.event_id.length === 0 ||
+    typeof claims.iat !== 'number' ||
+    !Number.isFinite(claims.iat) ||
+    typeof claims.exp !== 'number' ||
+    !Number.isFinite(claims.exp)
+  ) {
+    throw new Error('Invalid trigger event token.');
+  }
+  const nowSeconds = Math.floor(nowMs / 1000);
+  if (claims.exp <= nowSeconds || claims.iat > nowSeconds + 30) {
+    throw new Error('Trigger event token expired.');
+  }
+  return claims as PlayTriggerEventAdmissionTokenClaims;
+}
+
+export async function mintSignalRadarInboundReceiptToken(input: {
+  orgId: string;
+  receiptId: string;
+  nowMs?: number;
+}): Promise<string> {
+  return await mintSignalRadarInboundReceiptTokenShared(input);
+}
+
+export async function verifySignalRadarInboundReceiptToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<SignalRadarInboundReceiptTokenClaims> {
+  const segments = token.split('.');
+  if (segments.length !== 3) throw new Error('Invalid inbound receipt token.');
+  const [encodedHeader, encodedClaims, signature] = segments;
+  const header = decodeJson<Record<string, unknown>>(encodedHeader);
+  if (header.alg !== 'HS256' || header.typ !== 'JWT') {
+    throw new Error('Invalid inbound receipt token.');
+  }
+  const expectedSignature = await signTokenMaterial(
+    `${encodedHeader}.${encodedClaims}`,
+  );
+  if (
+    !timingSafeEqual(fromBase64Url(signature), fromBase64Url(expectedSignature))
+  ) {
+    throw new Error('Invalid inbound receipt token.');
+  }
+  const claims = decodeJson<Record<string, unknown>>(encodedClaims);
+  if (
+    claims.v !== INTERNAL_BOOTSTRAP_TOKEN_VERSION ||
+    claims.iss !== INTERNAL_BOOTSTRAP_TOKEN_ISSUER ||
+    claims.aud !== SIGNAL_RADAR_INBOUND_RECEIPT_AUDIENCE ||
+    claims.purpose !== SIGNAL_RADAR_INBOUND_RECEIPT_PURPOSE ||
+    claims.sub !== 'signal_radar_inbound_receipt_dispatcher' ||
+    typeof claims.org_id !== 'string' ||
+    claims.org_id.length === 0 ||
+    typeof claims.receipt_id !== 'string' ||
+    claims.receipt_id.length === 0 ||
+    typeof claims.iat !== 'number' ||
+    !Number.isFinite(claims.iat) ||
+    typeof claims.exp !== 'number' ||
+    !Number.isFinite(claims.exp)
+  ) {
+    throw new Error('Invalid inbound receipt token.');
+  }
+  const nowSeconds = Math.floor(nowMs / 1000);
+  if (claims.exp <= nowSeconds || claims.iat > nowSeconds + 30) {
+    throw new Error('Inbound receipt token expired.');
+  }
+  return claims as SignalRadarInboundReceiptTokenClaims;
+}
+
 /**
  * Mints a durable, narrowly scoped opt-out command. It never expires because
  * an old notification must remain usable to stop future email; rotating the

package/dist/bundling-sources/shared_libs/play-runtime/play-admission-outcome.ts

@@ -0,0 +1,134 @@
+import {
+  PLAY_SECRET_UNAVAILABLE,
+  playSecretUnavailableErrorFrom,
+} from '../plays/secrets/errors';
+
+/**
+ * Stable failure codes written onto a durable webhook receipt or cron
+ * occurrence. These are an admission ABI: a source can outlive the Vercel
+ * build that classified it, so route-local error classes are not a contract.
+ */
+export const PLAY_ADMISSION_INTERNAL_FAILURE =
+  'INTERNAL_ADMISSION_FAILURE' as const;
+export const PLAY_ADMISSION_PAYLOAD_UNREADABLE = 'PAYLOAD_UNREADABLE' as const;
+/**
+ * An invalid JSON string, so it cannot be a payload produced by JSON.stringify.
+ * This preserves the established Convex action return-object contract while a
+ * new adapter can still distinguish verified envelope corruption from an
+ * arbitrary transport or Runtime parsing error.
+ */
+export const PLAY_ADMISSION_PAYLOAD_UNREADABLE_SENTINEL =
+  '\u0000deepline:payload-unreadable';
+export const PLAY_RUN_PRE_RUN_VALIDATION_FAILED =
+  'PLAY_RUN_PRE_RUN_VALIDATION_FAILED' as const;
+export const RUNTIME_DB_SESSION_PRELOAD_INCOMPLETE =
+  'RUNTIME_DB_SESSION_PRELOAD_INCOMPLETE' as const;
+
+export type PlayAdmissionBlockedCode =
+  | typeof PLAY_ADMISSION_PAYLOAD_UNREADABLE
+  | typeof PLAY_SECRET_UNAVAILABLE
+  | typeof PLAY_RUN_PRE_RUN_VALIDATION_FAILED
+  | typeof RUNTIME_DB_SESSION_PRELOAD_INCOMPLETE;
+
+export type PlayAdmissionRetryableCode = typeof PLAY_ADMISSION_INTERNAL_FAILURE;
+
+export type PlayAdmissionFailure =
+  | {
+      /** Preserve the source and let its bounded transport retry. */
+      disposition: 'retry';
+      code: PlayAdmissionRetryableCode;
+      message: string;
+    }
+  | {
+      /** Retain the source as the pre-admission DLQ and release transport capacity. */
+      disposition: 'blocked';
+      code: PlayAdmissionBlockedCode;
+      message: string;
+    };
+
+const TERMINAL_PRE_ADMISSION_CODES = new Set<PlayAdmissionBlockedCode>([
+  PLAY_RUN_PRE_RUN_VALIDATION_FAILED,
+  RUNTIME_DB_SESSION_PRELOAD_INCOMPLETE,
+]);
+
+function stableErrorCode(error: unknown): string | null {
+  if (error === null || typeof error !== 'object') return null;
+  const code = (error as { code?: unknown }).code;
+  return typeof code === 'string' ? code : null;
+}
+
+function blocked(code: PlayAdmissionBlockedCode): PlayAdmissionFailure {
+  return {
+    disposition: 'blocked',
+    code,
+    message:
+      code === PLAY_SECRET_UNAVAILABLE
+        ? 'The Play configuration is unavailable. Repair it, then retry this delivery.'
+        : 'This delivery needs attention before it can be retried.',
+  };
+}
+
+/**
+ * Only the receipt adapter may raise this while decoding its durable JSON
+ * envelope, before it has called Runtime admission. A generic `SyntaxError`
+ * can come from a driver, generated code, or an uncertain submit path, so it
+ * must retain the safe retry disposition.
+ */
+export class PlayAdmissionPayloadDecodeError extends Error {
+  constructor(options?: { cause?: unknown }) {
+    super('Stored Play admission payload could not be decoded.');
+    this.name = 'PlayAdmissionPayloadDecodeError';
+    // This module is also compiled by Convex with ES2021 library types.
+    // Attach the diagnostic cause without Error's ES2022 two-argument overload.
+    if (options?.cause !== undefined) {
+      (this as { cause?: unknown }).cause = options.cause;
+    }
+  }
+}
+
+/**
+ * Classifies only failures that occur before the Runtime Run + Absurd task
+ * transaction. Unknown errors remain retryable because a lost response cannot
+ * prove that the atomic submission did not commit. Known invalid pinned input
+ * is terminal for this source and must not occupy every Workpool attempt.
+ */
+export function classifyPlayAdmissionFailure(
+  error: unknown,
+): PlayAdmissionFailure {
+  if (error instanceof PlayAdmissionPayloadDecodeError) {
+    return blocked(PLAY_ADMISSION_PAYLOAD_UNREADABLE);
+  }
+  if (playSecretUnavailableErrorFrom(error)) {
+    return blocked(PLAY_SECRET_UNAVAILABLE);
+  }
+  const code = stableErrorCode(error);
+  if (
+    code !== null &&
+    TERMINAL_PRE_ADMISSION_CODES.has(code as PlayAdmissionBlockedCode)
+  ) {
+    return blocked(code as PlayAdmissionBlockedCode);
+  }
+  return {
+    disposition: 'retry',
+    code: PLAY_ADMISSION_INTERNAL_FAILURE,
+    message:
+      'Deepline could not start this delivery yet. It will retry automatically.',
+  };
+}
+
+/**
+ * Signals a retryable private-admission response to Workpool without making
+ * the route or a source-specific adapter re-interpret arbitrary thrown text.
+ */
+export class PlayAdmissionRetryableError extends Error {
+  constructor(
+    readonly code: PlayAdmissionRetryableCode,
+    options?: { cause?: unknown },
+  ) {
+    super('Play admission is retryable.');
+    this.name = 'PlayAdmissionRetryableError';
+    if (options?.cause !== undefined) {
+      (this as { cause?: unknown }).cause = options.cause;
+    }
+  }
+}

package/dist/bundling-sources/shared_libs/play-runtime/play-runs/admission/contracts.ts

@@ -54,3 +54,16 @@ export class PlayRunLaunchConflictError extends Error {
     this.name = 'PlayRunLaunchConflictError';
   }
 }
+
+/** A fenced replay named a Run that was never durably admitted. */
+export class PlayRunAdmissionReplayMissingError extends Error {
+  readonly code = 'PLAY_RUN_ADMISSION_REPLAY_MISSING';
+
+  constructor(runId: string, options?: { cause?: unknown }) {
+    super(
+      `Play run "${runId}" does not exist for an existing-only admission.`,
+      options,
+    );
+    this.name = 'PlayRunAdmissionReplayMissingError';
+  }
+}

package/dist/bundling-sources/shared_libs/play-runtime/play-runs/admission/index.ts

@@ -1,6 +1,9 @@
 export { createPlayRunAdmissionJob } from '../../play-runs/admission/job';
 export { createPostgresPlayRunAdmissionPorts } from '../../play-runs/admission/postgres-adapter';
-export { PlayRunLaunchConflictError } from '../../play-runs/admission/contracts';
+export {
+  PlayRunAdmissionReplayMissingError,
+  PlayRunLaunchConflictError,
+} from '../../play-runs/admission/contracts';
 export type {
   PlayRunAdmissionInput,
   PlayRunAdmissionJob,

package/dist/bundling-sources/shared_libs/play-runtime/play-runs/admission/postgres-adapter.ts

@@ -3,6 +3,7 @@ import {
   type PostgresSchedulerQueryClient,
 } from '../../scheduler-backends/postgres';
 import {
+  PlayRunAdmissionReplayMissingError,
   PlayRunLaunchConflictError,
   type PlayRunAdmissionInput,
   type PlayRunAdmissionReceipt,
@@ -39,6 +40,11 @@ export function createPostgresPlayRunAdmissionPorts(input: {
               cause: error,
             });
           }
+          if (isExistingOnlyReplayMissing(error)) {
+            throw new PlayRunAdmissionReplayMissingError(admission.launch.runId, {
+              cause: error,
+            });
+          }
           throw error;
         }
       },
@@ -46,6 +52,13 @@ export function createPostgresPlayRunAdmissionPorts(input: {
   };
 }
 
+function isExistingOnlyReplayMissing(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    /existing-only admission/i.test(error.message)
+  );
+}
+
 function isLaunchConflict(error: unknown): boolean {
   return (
     error instanceof Error &&

package/dist/bundling-sources/shared_libs/play-runtime/play-webhook-admission-probe.ts

@@ -0,0 +1,32 @@
+/**
+ * The private Workpool dispatcher stops waiting for Vercel at this bound. A
+ * client abort does not prove the Vercel handler stopped, so it is not by
+ * itself safe for cleanup to recover an in-flight submit.
+ */
+export const PLAY_WEBHOOK_ADMISSION_PROBE_DISPATCH_REQUEST_MAX_MS = 60_000;
+
+/**
+ * The final Vercel-side Runtime admission can make one pooled read and one
+ * atomic scheduler submit. Each is bounded by a 5s acquire plus 30s query
+ * timeout; retain five seconds for in-process handoff/settlement.
+ */
+export const PLAY_WEBHOOK_ADMISSION_PROBE_SCHEDULER_COMMIT_TAIL_MS = 75_000;
+
+/** Vercel must survive the dispatch client timeout plus its commit tail. */
+export const PLAY_WEBHOOK_ADMISSION_PROBE_VERCEL_MAX_DURATION_SECONDS = 135;
+
+/** A confirmed submission is valid until the bounded handler can finish. */
+export const PLAY_WEBHOOK_ADMISSION_PROBE_SUBMISSION_MAX_MS =
+  PLAY_WEBHOOK_ADMISSION_PROBE_VERCEL_MAX_DURATION_SECONDS * 1_000;
+
+/**
+ * Keep a source fence live after Vercel's bounded submission window. This
+ * avoids reclaiming on the exact platform deadline while a final scheduler
+ * connection teardown or commit acknowledgement is still resolving.
+ */
+export const PLAY_WEBHOOK_ADMISSION_PROBE_CLEANUP_GRACE_MS = 5_000;
+
+/** Cleanup may reclaim a killed probe only after submission plus grace. */
+export const PLAY_WEBHOOK_ADMISSION_PROBE_SUBMISSION_LEASE_MS =
+  PLAY_WEBHOOK_ADMISSION_PROBE_SUBMISSION_MAX_MS +
+  PLAY_WEBHOOK_ADMISSION_PROBE_CLEANUP_GRACE_MS;

package/dist/bundling-sources/shared_libs/play-runtime/play-webhook-identity.ts

@@ -0,0 +1,28 @@
+import { createHash } from 'node:crypto';
+import { buildPlayWorkflowFamilyKey } from './run-identity';
+
+/**
+ * The deterministic identity shared by a durable webhook source, its Runtime
+ * Run, and its Absurd task. This is intentionally dependency-free: provider
+ * and CLI tooling must be able to reconstruct it without importing Vercel
+ * admission code.
+ */
+export function buildPlayWebhookIdentity(input: {
+  bindingId: string;
+  dedupeKey: string;
+  playName: string;
+}) {
+  const deliveryHash = createHash('sha256')
+    .update(input.bindingId)
+    .update('\0')
+    .update(input.dedupeKey)
+    .digest('hex');
+  const workflowFamilyKey = buildPlayWorkflowFamilyKey(input.playName);
+  const runId = `play/${workflowFamilyKey}/webhook/${deliveryHash.slice(0, 32)}`;
+  return {
+    eventId: `pwh_${deliveryHash}`,
+    workflowId: runId,
+    runId,
+    workflowFamilyKey,
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backend.ts

@@ -41,6 +41,13 @@ export type { PlayRunInputPayload };
 
 export type PlaySchedulerSubmitInput = {
   runId: string;
+  /**
+   * Admit an exact replay only. This is an ephemeral admission instruction:
+   * it is deliberately excluded from the persisted launch identity so a
+   * delivery retried after its binding is disabled can observe its original
+   * Run without changing that Run's immutable launch contract.
+   */
+  existingOnly?: boolean;
   /** First-class async-child lineage. Absent for root launches. */
   parentRunId?: string | null;
   rootRunId?: string | null;