Tighten failure and manifest contracts

docs/spec/api/README.md

@@ -22,8 +22,9 @@ deletion and cancellation semantics still use this request identity.
 
 Internal claim uses job ID plus `operation_id` because no attempt exists yet.
 Renew, progress, and outcome use attempt ID, fencing token, worker incarnation,
-and `operation_id`. A replay has the original effect; a different, stale, or
-non-authoritative tuple returns `precondition_failed` without mutation.
+and `operation_id`. Each operation identity retains a request fingerprint. An
+exact replay has the original effect; a changed worker, fence, payload, stale,
+or non-authoritative tuple returns `precondition_failed` without mutation.
 
 ## Authorization and errors
 
@@ -55,6 +56,11 @@ unauthorized, absent, and never-committed results are not exposed. The hard
 delete endpoint returns the durable deletion resource established by the
 architecture.
 
+Worker failure outcomes accept only attempt-reportable runtime classes and do
+not accept a caller-supplied retryable flag. The service derives the durable
+disposition from the class mapping in the architecture. Validation,
+cancellation, and lost-attempt projection use their dedicated boundaries.
+
 ## WebSocket replay
 
 An HTTP job or list snapshot carries `event_cursor` at its consistency

docs/spec/api/openapi.yaml

@@ -515,15 +515,47 @@ components:
           type: integer
           minimum: 0
     JobFailure:
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [class, retryable, message]
+          properties:
+            class:
+              type: string
+              enum: [validation, authorization, source_not_found, source_changed, cancelled]
+            retryable:
+              const: false
+            message:
+              type: string
+              maxLength: 500
+            safe_details:
+              type: object
+              additionalProperties:
+                type: [string, integer, boolean, 'null']
+        - type: object
+          additionalProperties: false
+          required: [class, retryable, message]
+          properties:
+            class:
+              type: string
+              enum: [transient_source, transient_target, integrity, capacity, internal, lost_attempt]
+            retryable:
+              const: true
+            message:
+              type: string
+              maxLength: 500
+            safe_details:
+              type: object
+              additionalProperties:
+                type: [string, integer, boolean, 'null']
+    AttemptRuntimeFailure:
       type: object
       additionalProperties: false
-      required: [class, retryable, message]
+      required: [class, message]
       properties:
         class:
           type: string
-          enum: [validation, authorization, source_not_found, source_changed, transient_source, transient_target, integrity, capacity, internal, cancelled, lost_attempt]
-        retryable:
-          type: boolean
+          enum: [authorization, source_not_found, source_changed, transient_source, transient_target, integrity, capacity, internal]
         message:
           type: string
           maxLength: 500
@@ -722,4 +754,4 @@ components:
                     kind:
                       const: failure
                     failure:
-                      $ref: '#/components/schemas/JobFailure'
+                      $ref: '#/components/schemas/AttemptRuntimeFailure'