@semiont/gateway 0.5.32 → 0.5.34

package/dist/openapi.json

@@ -3097,6 +3097,13 @@
             "type": "string",
             "description": "Optional correlation id echoed from the originating command. When present, the failure event can be matched back to the specific command that failed."
           },
+          "code": {
+            "type": "string",
+            "enum": [
+              "peer-unavailable"
+            ],
+            "description": "Machine-readable failure class, for consumers that must BRANCH on why a command failed rather than log it. Optional and deliberately sparse: absent means 'no class declared', and every existing failure stays that way. An enum rather than a free string so the vocabulary has an owner — an unconstrained code is a mirror with no gate, and adding one should be a deliberate spec change. `message` remains the human-readable text and is unaffected. Members: `peer-unavailable` — the channel this command was sent on has no subscriber, i.e. the service that answers it has not connected yet. Transient by nature (a peer still starting), which is what distinguishes it from a refusal: retrying is the correct response."
+          },
           "message": {
             "type": "string",
             "description": "Human-readable error message"
@@ -3972,6 +3979,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 +4770,9 @@
           },
           "result": {
             "$ref": "#/components/schemas/JobResult"
+          },
+          "durability": {
+            "$ref": "#/components/schemas/DurabilityEvidence"
           }
         },
         "required": [
@@ -4786,6 +4814,9 @@
             "type": "object",
             "additionalProperties": true,
             "description": "Full result object for extensibility"
+          },
+          "durability": {
+            "$ref": "#/components/schemas/DurabilityEvidence"
           }
         },
         "required": [
@@ -4878,16 +4909,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 +4988,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 +5003,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 +5125,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 +5150,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 +5497,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 +6038,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.34",
   "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.34",
+    "@semiont/make-meaning": "0.5.34",
+    "@semiont/observability": "0.5.34",
     "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",