[codex] Structure APNs delivery job errors

infra/relay/src/agentActivity/ApnsDeliveries.test.ts

@@ -611,6 +611,22 @@ describe("ApnsDeliveries", () => {
     }).pipe(Effect.provide(makeLayer({ attempts, queuedJobs })));
   });
 
+  it.effect("preserves the schema cause for invalid queue payloads", () => {
+    const attempts: Array<DeliveryAttempts.DeliveryAttemptInput> = [];
+
+    return Effect.gen(function* () {
+      const deliveries = yield* ApnsDeliveries.ApnsDeliveries;
+      const error = yield* Effect.flip(deliveries.processSignedJob({ invalid: true }));
+
+      expect(error).toMatchObject({
+        _tag: "ApnsDeliveryJobQueuePayloadInvalid",
+        receivedType: "object",
+        message: "Invalid APNs delivery queue job with object payload.",
+      });
+      expect(error.cause).toMatchObject({ _tag: "SchemaError" });
+    }).pipe(Effect.provide(makeLayer({ attempts })));
+  });
+
   it.effect("processes signed jobs through APNs and records attempts", () => {
     const attempts: Array<DeliveryAttempts.DeliveryAttemptInput> = [];
     const payload = makeApnsDeliveryJobPayload({

infra/relay/src/agentActivity/ApnsDeliveries.ts

@@ -640,7 +640,13 @@ export const make = Effect.gen(function* () {
     "relay.apns_deliveries.process_signed_job",
   )(function* (body) {
     const signedJob = yield* decodeSignedApnsDeliveryJob(body).pipe(
-      Effect.mapError(() => new ApnsDeliveryJobQueuePayloadInvalid()),
+      Effect.mapError(
+        (cause) =>
+          new ApnsDeliveryJobQueuePayloadInvalid({
+            receivedType: Array.isArray(body) ? "array" : body === null ? "null" : typeof body,
+            cause,
+          }),
+      ),
     );
     const now = yield* DateTime.now;
     const payload = verifySignedApnsDeliveryJob({
@@ -661,7 +667,14 @@ export const make = Effect.gen(function* () {
         case "live_activity_start":
         case "live_activity_update":
           if (payload.aggregate === null) {
-            return Effect.fail(new ApnsDeliveryJobLiveActivityAggregateMissing());
+            return Effect.fail(
+              new ApnsDeliveryJobLiveActivityAggregateMissing({
+                jobId: payload.jobId,
+                kind: payload.kind,
+                userId: payload.target.userId,
+                deviceId: payload.target.deviceId,
+              }),
+            );
           }
           return sendLiveActivity({
             target: {
@@ -686,7 +699,13 @@ export const make = Effect.gen(function* () {
           });
         case "push_notification":
           if (payload.notification === null) {
-            return Effect.fail(new ApnsDeliveryJobPushNotificationMissing());
+            return Effect.fail(
+              new ApnsDeliveryJobPushNotificationMissing({
+                jobId: payload.jobId,
+                userId: payload.target.userId,
+                deviceId: payload.target.deviceId,
+              }),
+            );
           }
           return sendPushNotification({
             target: {

infra/relay/src/agentActivity/apnsDeliveryJobs.test.ts

@@ -70,6 +70,11 @@ describe("apnsDeliveryJobs", () => {
 
     expect(result).toMatchObject({
       _tag: "ApnsDeliveryJobSignatureInvalid",
+      jobId: "job-1",
+      kind: "live_activity_end",
+      userId: "user-1",
+      deviceId: "device-1",
+      message: "Invalid signature for APNs delivery job job-1.",
     });
   });
 
@@ -94,7 +99,11 @@ describe("apnsDeliveryJobs", () => {
 
     expect(result).toMatchObject({
       _tag: "ApnsDeliveryJobLiveActivityAggregateMissing",
-      message: "Live Activity start/update jobs require an aggregate.",
+      jobId: "job-start-invalid",
+      kind: "live_activity_start",
+      userId: "user-1",
+      deviceId: "device-1",
+      message: "APNs live activity start job job-start-invalid requires an aggregate.",
     });
   });
 
@@ -120,7 +129,10 @@ describe("apnsDeliveryJobs", () => {
 
     expect(result).toMatchObject({
       _tag: "ApnsDeliveryJobPushNotificationAggregateUnexpected",
-      message: "Push notification jobs must not carry aggregate state.",
+      jobId: "job-push-invalid",
+      userId: "user-1",
+      deviceId: "device-1",
+      message: "APNs push notification job job-push-invalid must not carry aggregate state.",
     });
   });
 
@@ -195,7 +207,12 @@ describe("apnsDeliveryJobs", () => {
       }),
     ).toMatchObject({
       _tag: "ApnsDeliveryJobCreatedAtInvalid",
-      message: "Invalid APNs delivery job creation time.",
+      jobId: "job-window",
+      kind: "live_activity_end",
+      userId: "user-1",
+      deviceId: "device-1",
+      createdAt: "not-a-date",
+      message: "APNs delivery job job-window has invalid creation time not-a-date.",
     });
     expect(
       verifySignedApnsDeliveryJob({
@@ -205,7 +222,14 @@ describe("apnsDeliveryJobs", () => {
       }),
     ).toMatchObject({
       _tag: "ApnsDeliveryJobTimeWindowInvalid",
-      message: "Invalid APNs delivery job time window.",
+      jobId: "job-window",
+      kind: "live_activity_end",
+      userId: "user-1",
+      deviceId: "device-1",
+      createdAt: "2026-05-25T00:00:00.000Z",
+      expiresAt: "2026-05-24T23:59:59.000Z",
+      message:
+        "APNs delivery job job-window has invalid time window 2026-05-25T00:00:00.000Z to 2026-05-24T23:59:59.000Z.",
     });
     expect(
       verifySignedApnsDeliveryJob({
@@ -215,7 +239,14 @@ describe("apnsDeliveryJobs", () => {
       }),
     ).toMatchObject({
       _tag: "ApnsDeliveryJobTimeWindowTooLong",
-      message: "APNs delivery job time window is too long.",
+      jobId: "job-window",
+      kind: "live_activity_end",
+      userId: "user-1",
+      deviceId: "device-1",
+      createdAt: "2026-05-25T00:00:00.000Z",
+      expiresAt: "2026-05-25T00:10:01.000Z",
+      message:
+        "APNs delivery job job-window time window 2026-05-25T00:00:00.000Z to 2026-05-25T00:10:01.000Z is too long.",
     });
   });
 });