Fix/max retries deadletter queue

.env.example

@@ -145,7 +145,7 @@ AAAS_ADMIN_ENAMES=""
 # Secret used to sign AaaS portal session JWTs
 AAAS_JWT_SECRET="replace-with-a-strong-secret"
 # Webhook delivery tuning
-AWARENESS_MAX_ATTEMPTS=8
+AWARENESS_MAX_ATTEMPTS=3
 AWARENESS_DELIVERY_POLL_MS=2000
 # The one-time Neo4j backfill reuses the standard NEO4J_URI / NEO4J_USER /
 # NEO4J_PASSWORD vars at the top of this file - it reads evault-core's graph

docs/docs/Services/Awareness-as-a-Service.md

@@ -160,7 +160,7 @@ AaaS is designed to be dropped in with **zero receiver-side changes**:
 | `AWARENESS_SERVICE_URL` | (evault-core) where to POST packets |
 | `AAAS_ADMIN_ENAMES` | Comma-separated admin eNames |
 | `AAAS_JWT_SECRET` | Signs portal session JWTs |
-| `AWARENESS_MAX_ATTEMPTS` | Delivery attempts before dead-lettering (default 8) |
+| `AWARENESS_MAX_ATTEMPTS` | Delivery attempts before dead-lettering (default 3) |
 | `AWARENESS_DELIVERY_POLL_MS` | Delivery engine poll interval (default 2000) |
 | `NEO4J_URI` / `NEO4J_USER` / `NEO4J_PASSWORD` | Standard eVault Neo4j vars — reused by the one-time backfill |
 | `PUBLIC_AWARENESS_API_URL` | (portal) AaaS API base URL |

services/awareness-service/api/src/config.ts

@@ -27,7 +27,7 @@ export const config = {
         .filter(Boolean),
     /** Secret used to sign portal session JWTs. */
     jwtSecret: process.env.AAAS_JWT_SECRET ?? "awareness-dev-secret",
-    maxAttempts: parseInt(process.env.AWARENESS_MAX_ATTEMPTS ?? "8", 10),
+    maxAttempts: parseInt(process.env.AWARENESS_MAX_ATTEMPTS ?? "3", 10),
     deliveryPollMs: parseInt(
         process.env.AWARENESS_DELIVERY_POLL_MS ?? "2000",
         10,

services/awareness-service/api/src/database/entities/Delivery.ts

@@ -11,7 +11,8 @@ export type DeliveryStatus =
     | "pending"
     | "delivering"
     | "delivered"
-    | "failed";
+    | "failed"
+    | "dead";
 
 /**
  * A queued webhook delivery of one packet to one subscription. The unique

services/awareness-service/api/src/openapi.ts

@@ -107,7 +107,13 @@ export const openApiDocument = {
                     packetId: { type: "string" },
                     status: {
                         type: "string",
-                        enum: ["pending", "delivering", "delivered", "failed"],
+                        enum: [
+                            "pending",
+                            "delivering",
+                            "delivered",
+                            "failed",
+                            "dead",
+                        ],
                     },
                     attempts: { type: "integer" },
                     nextAttemptAt: { type: "string", format: "date-time" },

services/awareness-service/api/src/services/DeliveryEngine.ts

@@ -92,15 +92,19 @@ export class DeliveryEngine {
             .update(Delivery)
             .set({ status: "delivering" })
             .where(
+                // Only pending/failed deliveries still under the attempt
+                // limit are claimable. `dead` deliveries (and any that
+                // already hit the cap) are terminal and never re-claimed.
                 `id IN (
                     SELECT id FROM deliveries
                     WHERE status IN ('pending', 'failed')
+                      AND attempts < :maxAttempts
                       AND "nextAttemptAt" <= now()
                     ORDER BY "nextAttemptAt"
                     LIMIT :limit
                     FOR UPDATE SKIP LOCKED
                 )`,
-                { limit: BATCH_SIZE },
+                { limit: BATCH_SIZE, maxAttempts: config.maxAttempts },
             )
             .returning("*")
             .execute();
@@ -181,8 +185,11 @@ export class DeliveryEngine {
         const deliveryRepo = AppDataSource.getRepository(Delivery);
 
         if (attempts >= config.maxAttempts) {
+            // Terminal: mark `dead` so the engine never re-claims it. (Using
+            // `failed` here let exhausted deliveries be picked up again every
+            // tick, inflating attempts and spawning duplicate dead letters.)
             await deliveryRepo.update(delivery.id, {
-                status: "failed",
+                status: "dead",
                 attempts,
                 lastError: message,
                 lastResponseStatus: responseStatus,