@semiont/gateway 0.5.32 → 0.5.33

package/dist/openapi.json

@@ -3972,6 +3972,24 @@
           "resourceId"
         ]
       },
+      "DurabilityEvidence": {
+        "type": "string",
+        "enum": [
+          "acknowledged",
+          "probe-confirmed",
+          "probe-refused",
+          "probe-unreachable"
+        ],
+        "description": "How a job's annotations were established as durable — the OBSERVATION, never a conclusion drawn from it. 'acknowledged': the event log confirmed the batch (mark:commit-ok). 'probe-confirmed': the acknowledgement was lost and a later read found the batch's last annotation present — true, but a weaker claim than an ack, since it rests on the log appending a batch in order and stopping at the first failure. 'probe-refused': the read returned a failure reply; note this does NOT assert the annotations are absent, because a read that failed for its own reasons answers on the same channel. 'probe-unreachable': no answer came at all, so nothing was established either way. ABSENT means the question never arose — a job that committed no annotations. Never defaulted: a manufactured value here is a claim nobody made, in a log nobody can rewrite."
+      },
+      "FailureClass": {
+        "type": "string",
+        "enum": [
+          "transient",
+          "deterministic"
+        ],
+        "description": "Worker-side classification of a job failure, made where the error is still typed (at the gateway it is already a flattened string, and message-regex classification is the drift this exists to avoid). 'deterministic' — the same request cannot succeed on a second attempt — skips the retry budget. ABSENT means unrecognised, which is deliberately not the same claim as 'transient': only KNOWN-deterministic failures carry the class, because mis-reading a transient failure as deterministic halves reliability while the reverse costs one wasted attempt."
+      },
       "GatheredContext": {
         "type": "object",
         "description": "Context gathered for a gather.* call — consumed by yield.* (generation) and the matcher. A shared base (graph, semanticContext, metadata, inferredRelationshipSummary) plus a discriminated `focus` that names the anchor: an annotation or a whole resource.",
@@ -4745,6 +4763,9 @@
           },
           "result": {
             "$ref": "#/components/schemas/JobResult"
+          },
+          "durability": {
+            "$ref": "#/components/schemas/DurabilityEvidence"
           }
         },
         "required": [
@@ -4786,6 +4807,9 @@
             "type": "object",
             "additionalProperties": true,
             "description": "Full result object for extensibility"
+          },
+          "durability": {
+            "$ref": "#/components/schemas/DurabilityEvidence"
           }
         },
         "required": [
@@ -4878,16 +4902,14 @@
             "description": "Entity-type units whose annotations were fully emitted before this failure (checkpointed resume). The queue records them on the retried job's metadata; a retried claim skips them so completed work is neither redone nor duplicated."
           },
           "failureClass": {
-            "type": "string",
-            "enum": [
-              "transient",
-              "deterministic"
-            ],
-            "description": "Worker-side classification of the failure, made where the error is still typed. 'deterministic' — the same request cannot succeed on a second attempt — skips the retry budget; absent or 'transient' retries as before. Only KNOWN-deterministic failures carry the class."
+            "$ref": "#/components/schemas/FailureClass"
           },
           "willRetry": {
             "type": "boolean",
             "description": "Whether the queue will re-queue this job for another attempt. Computed by the worker from the SAME predicate the queue applies at failJob (one decision site, `willRetryAfter` in @semiont/jobs) using the retry budget carried on the claimed record. FALSE (or absent) means this failure is TERMINAL: a client's job-watch stream ends here. TRUE means the work continues on a fresh attempt — the failure is an event, not the end, and a stream that terminated on it would report a recovering run as a failed one (JOB-RESTART-SAFETY P5)."
+          },
+          "durability": {
+            "$ref": "#/components/schemas/DurabilityEvidence"
           }
         },
         "required": [
@@ -4959,7 +4981,7 @@
       },
       "JobFailedPayload": {
         "type": "object",
-        "description": "Payload for job:failed domain event",
+        "description": "Payload for the job:failed domain event — a permanent fact of the resource, not operational state. It carries the judgments the worker COMPUTED, not just its message: at the log they are otherwise unrecoverable, the only remaining witness being a flattened English string.",
         "properties": {
           "jobId": {
             "type": "string"
@@ -4974,8 +4996,15 @@
           "error": {
             "type": "string"
           },
-          "details": {
-            "type": "string"
+          "failureClass": {
+            "$ref": "#/components/schemas/FailureClass"
+          },
+          "willRetry": {
+            "type": "boolean",
+            "description": "Whether the worker computed that the queue would re-queue this job (same predicate the queue applies, `willRetryAfter`). Absent means the worker stated nothing. Without it a reader of the log cannot tell a run recovering across several job:failed events from that many dead jobs."
+          },
+          "durability": {
+            "$ref": "#/components/schemas/DurabilityEvidence"
           }
         },
         "required": [
@@ -5089,6 +5118,10 @@
             "type": "integer",
             "description": "Entities found so far (reference-annotation)"
           },
+          "entitiesExpected": {
+            "type": "integer",
+            "description": "Cumulative mentions the count-verifier priced across the pieces accepted so far — the denominator for a real progress bar (found of ~expected). Approximate by nature (the count saturates on very large pieces) and monotonically growing within a run. ABSENT when the provider does not verify detection yield, or before any piece has been priced: no claim, never zero."
+          },
           "entitiesEmitted": {
             "type": "integer",
             "description": "Annotations emitted so far (reference-annotation)"
@@ -5110,6 +5143,29 @@
                 "persistedCount": {
                   "type": "integer",
                   "description": "Annotations actually persisted for it — post-dedupe and post-durability-acknowledgement, so it counts what the event log holds, not what the model proposed. Beside foundCount this is the per-unit yield the sizing work is judged by. Present on flows whose units persist as they complete (reference-annotation); the tagging flow reports the same fact as byCategory on its result, because its annotations are built after the per-category loop."
+                },
+                "underReported": {
+                  "type": "object",
+                  "description": "Present only when pieces of this unit were accepted at the subdivision floor while a count call said more was present. The unit completed, but incompletely — this carries the EVIDENCE (found vs counted, over how many pieces), never a judgment against any expected yield. Absent means complete: genuinely absent, not defaulted.",
+                  "properties": {
+                    "pieces": {
+                      "type": "integer",
+                      "description": "Floor-accepted pieces in this unit."
+                    },
+                    "found": {
+                      "type": "integer",
+                      "description": "Annotations extraction did find on those pieces — every span write-time-verified."
+                    },
+                    "counted": {
+                      "type": "integer",
+                      "description": "Mentions the count calls reported across those pieces (approximate by nature)."
+                    }
+                  },
+                  "required": [
+                    "pieces",
+                    "found",
+                    "counted"
+                  ]
                 }
               },
               "required": [
@@ -5434,6 +5490,10 @@
           "errors": {
             "type": "integer",
             "description": "Number of errors encountered"
+          },
+          "underReportedPieces": {
+            "type": "integer",
+            "description": "Total floor-accepted under-reported pieces across the job's units. Absent means none — the per-unit evidence rides the terminal progress frame's completedItems; this keeps the result self-describing without the progress stream."
           }
         },
         "required": [
@@ -5971,7 +6031,7 @@
             "properties": {
               "persisted": {
                 "type": "integer",
-                "description": "Annotations this commit appended to the event log. Equals the batch size on success — a retry re-appends what already landed rather than counting it out, because the annotation fold is idempotent by id and the log is append-only. Not a dedupe count."
+                "description": "Annotations the command named that are durable in the event log. Equals the batch size on success, on a first commit and on a retry alike — the commit appends only what the resource does not already hold, so a wholly-redundant retry has still succeeded and says so. Not an append tally: a caller must never have to read a 0 as 'all good'."
               },
               "annotationIds": {
                 "type": "array",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/gateway",
-  "version": "0.5.32",
+  "version": "0.5.33",
   "type": "module",
   "description": "Semiont gateway server - pre-built for npm consumption",
   "main": "dist/index.js",
@@ -30,13 +30,13 @@
     "@hono/swagger-ui": "^0.6.1",
     "@prisma/adapter-pg": "^7.10.0",
     "@prisma/client": "^7.10.0",
-    "@semiont/core": "0.5.32",
-    "@semiont/make-meaning": "0.5.32",
-    "@semiont/observability": "0.5.32",
+    "@semiont/core": "0.5.33",
+    "@semiont/make-meaning": "0.5.33",
+    "@semiont/observability": "0.5.33",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "argon2": "^0.45.1",
-    "hono": "^4.13.5",
+    "hono": "^4.13.7",
     "jsonwebtoken": "^9.0.2",
     "prisma": "^7.10.0",
     "winston": "^3.19.0",