@semiont/gateway 0.5.28 → 0.5.30

package/dist/openapi.json

@@ -1930,7 +1930,7 @@
           },
           "token": {
             "type": "string",
-            "description": "Short-lived access token (1 hour). Use as Authorization: Bearer header on API calls."
+            "description": "Short-lived access token. Use as Authorization: Bearer header on API calls. The TTL is deliberately NOT restated here — docs/system/administration/AUTHENTICATION.md holds the one table of token lifetimes, and a second copy is how this description came to claim an hour for a ten-minute token. A client must refresh from the refresh token rather than assume any particular window."
           },
           "refreshToken": {
             "type": "string",
@@ -2951,6 +2951,10 @@
             "type": "string",
             "description": "Optional resource scope for broadcast channels (e.g. resourceId). Publishers only — clients must never set this.",
             "minLength": 1
+          },
+          "clientId": {
+            "type": "string",
+            "description": "Routing address for this request's reply (CORRELATED-REPLY-ROUTING D1/D2): the emit doubles as a claim on the correlationId, and delivery matches BOTH this and the emitting principal. Top-level, not inside `payload` — a wire concern like `scope`, so it never enters a channel's domain type. Optional in the schema because a plain broadcast needs no return address; the route requires it when the channel is a registered request channel and the payload carries a correlationId."
           }
         },
         "required": [
@@ -3005,9 +3009,16 @@
                 }
               }
             }
+          },
+          "clientId": {
+            "type": "string",
+            "description": "Routing address for correlated replies (CORRELATED-REPLY-ROUTING D1): a UUID minted once per bus-client lifetime — per actor, NOT per connection, so it survives a make-before-break reconnect and both overlap connections share it. Required: a subscriber without one could never receive a correlated frame, and that must fail loudly here rather than silently at delivery. Not authentication — the JWT stays that; this is an unguessable routing address, never echoed into any payload or broadcast frame."
           }
         },
-        "additionalProperties": false
+        "additionalProperties": false,
+        "required": [
+          "clientId"
+        ]
       },
       "CloneResourceWithTokenResponse": {
         "type": "object",
@@ -3822,6 +3833,10 @@
         "type": "object",
         "description": "Progress payload emitted on the gather:annotation-progress SSE channel during LLM context gathering.",
         "properties": {
+          "correlationId": {
+            "type": "string",
+            "description": "The request this progress belongs to (CORRELATED-REPLY-ROUTING D3). Required: `CORRELATED_CHANNELS` derives every operation's progress channel into the delivery filter, so a frame without it cannot be matched to a claim and is silently dropped."
+          },
           "message": {
             "type": "string"
           },
@@ -3830,7 +3845,10 @@
             "minimum": 0,
             "maximum": 100
           }
-        }
+        },
+        "required": [
+          "correlationId"
+        ]
       },
       "GatherResourceComplete": {
         "type": "object",
@@ -4584,21 +4602,58 @@
       },
       "JobCancelRequest": {
         "type": "object",
-        "description": "Request to cancel a job",
+        "description": "Request to cancel a job. Target one running or pending job by `jobId` (JOB-RESTART-SAFETY P4), or a whole category of pending jobs by `jobType`. A `jobId`-targeted request that names a RUNNING job is honoured cooperatively by the owning worker, which stops at its next unit boundary and emits JobCancelCommand — the queue is never made to yank a running job out from under a live worker.",
         "properties": {
           "correlationId": {
             "type": "string",
             "description": "Correlation id for request/reply matching, set by the SDK's busRequest so the confirmed-write ack/failure routes back. Absent for the local cancelRequest UI signal."
           },
+          "jobId": {
+            "type": "string",
+            "description": "Cancel this one job. A pending job is cancelled immediately by the gateway; a running job is cancelled cooperatively by its worker. Takes precedence over jobType."
+          },
           "jobType": {
             "type": "string",
             "enum": [
               "annotation",
               "generation"
-            ]
+            ],
+            "description": "Cancel all PENDING jobs in this category — the bulk UI signal. Ignored when jobId is present."
+          }
+        }
+      },
+      "JobCancelCommand": {
+        "type": "object",
+        "description": "A worker's confirmation that it has cooperatively stopped a running job at a unit boundary (JOB-RESTART-SAFETY P4) — the queue moves the job to cancelled/. Distinct from JobCancelRequest (the client→worker REQUEST to stop): this is the worker announcing it did, so the running job is never yanked to cancelled/ out from under a live worker (the roach-motel race).",
+        "properties": {
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
+          },
+          "resourceId": {
+            "type": "string"
+          },
+          "jobId": {
+            "type": "string"
+          },
+          "jobType": {
+            "$ref": "#/components/schemas/JobType"
+          },
+          "annotationId": {
+            "type": "string",
+            "description": "Annotation this job is attached to, when applicable. Lets the UI route cancellation feedback to a specific annotation."
+          },
+          "completedUnits": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Entity-type units whose annotations were fully emitted before cancellation. Recorded on the cancelled job's metadata so the work already done stays visible."
           }
         },
         "required": [
+          "resourceId",
+          "jobId",
           "jobType"
         ]
       },
@@ -4789,6 +4844,25 @@
           },
           "error": {
             "type": "string"
+          },
+          "completedUnits": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "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."
+          },
+          "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)."
           }
         },
         "required": [
@@ -4798,6 +4872,30 @@
           "error"
         ]
       },
+      "JobCheckpointCommand": {
+        "type": "object",
+        "description": "Command to persist a running job's completed-unit checkpoint AT unit completion (JOB-RESTART-SAFETY P2). Distinct from JobFailCommand's checkpoint, which lands only on a clean failure: a worker that dies (crash/OOM/kill) never emits job:fail, so this durable, unthrottled write is what lets the janitor's stale-running recovery resume a dead worker's job rather than redo its finished units.",
+        "properties": {
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
+          },
+          "jobId": {
+            "type": "string"
+          },
+          "completedUnits": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Entity-type units whose annotations have been fully emitted so far. Unioned into the running job's metadata checkpoint; a retry after recovery skips them."
+          }
+        },
+        "required": [
+          "jobId",
+          "completedUnits"
+        ]
+      },
       "JobDeclinedResult": {
         "type": "object",
         "description": "Result of a job that completed without doing its work because the resource could not be read. Distinct from a failure: nothing went wrong, there was simply no text to work with — an encrypted or damaged PDF, a scan whose text could not be recognized, or a document that yielded nothing. The reasons are the extraction vocabulary the Smelter reports on `smelt:settled`, MINUS `no-extractor`: a media type that can never yield text (a zip, an image) is a bad request rather than a decline, so a worker asked to detect over one throws and the job reports `job:fail`. Everything here is a resource-specific outcome — the same media type would have succeeded on a different document.",
@@ -4983,6 +5081,10 @@
                 "foundCount": {
                   "type": "integer",
                   "description": "Annotations found for it."
+                },
+                "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."
                 }
               },
               "required": [
@@ -5800,6 +5902,71 @@
           "response"
         ]
       },
+      "MarkCommitCommand": {
+        "type": "object",
+        "description": "Bus command to persist a detection unit's annotations as one acknowledged batch (JOB-RESTART-SAFETY P6). Unlike mark:create, which is fire-and-forget and resolves when the bus accepts it, this command is answered only after every annotation is in the event log — so a worker can gate unit completion on durability rather than on emission. The batch is the unit: a partial commit is reported as a failure, and the worker retries the whole unit, which is safe because annotation ids are deterministic (P3).",
+        "properties": {
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
+          },
+          "correlationId": {
+            "type": "string",
+            "description": "Correlation id set by busRequest so the mark:commit-ok / mark:commit-failed reply routes back to the awaiting worker."
+          },
+          "resourceId": {
+            "type": "string",
+            "description": "Resource every annotation in this batch targets."
+          },
+          "annotations": {
+            "type": "array",
+            "description": "The unit's annotations, already built with deterministic ids. Re-committing an identical batch is a no-op rather than a duplicate.",
+            "items": {
+              "$ref": "#/components/schemas/Annotation"
+            }
+          }
+        },
+        "required": [
+          "correlationId",
+          "resourceId",
+          "annotations"
+        ]
+      },
+      "MarkCommitOk": {
+        "type": "object",
+        "description": "Durability acknowledgement for a mark:commit batch: every annotation named by the command is in the event log at the moment this is emitted.",
+        "properties": {
+          "correlationId": {
+            "type": "string",
+            "description": "Correlation id echoed from the mark:commit command so busRequest can match the reply."
+          },
+          "response": {
+            "type": "object",
+            "description": "What the commit persisted.",
+            "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."
+              },
+              "annotationIds": {
+                "type": "array",
+                "description": "Ids the batch covers, whether appended now or already present.",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "required": [
+              "persisted",
+              "annotationIds"
+            ]
+          }
+        },
+        "required": [
+          "correlationId",
+          "response"
+        ]
+      },
       "MarkCreateRequest": {
         "type": "object",
         "description": "Raw annotation creation intent — bus handler assembles the W3C annotation",

package/package.json

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