@semiont/gateway 0.5.29 → 0.5.31

package/dist/openapi.json

@@ -1688,10 +1688,13 @@
             "description": "Web Annotation creator — the entity that initiated the annotation. For human-driven work this is a Person; for autonomous-agent work this is a Software peer."
           },
           "created": {
-            "type": "string"
+            "type": "string",
+            "format": "date-time",
+            "description": "When the annotation was MADE — the authoring moment, carried from the event that created it. Not when a projection happened to write it: a store that rebuilds from the log must preserve this value, never restamp it."
           },
           "modified": {
-            "type": "string"
+            "type": "string",
+            "format": "date-time"
           },
           "generator": {
             "oneOf": [
@@ -1729,7 +1732,8 @@
           "type",
           "id",
           "motivation",
-          "target"
+          "target",
+          "created"
         ]
       },
       "AnnotationAddedPayload": {
@@ -1930,7 +1934,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",
@@ -2767,18 +2771,13 @@
       },
       "BrowseAnchoredTextResult": {
         "type": "object",
-        "description": "A resource's stored extraction outcome — the coordinate map with its provenance, or a named decline — or null when none has been derived. Null is the common case and not an error: a native text layer is read in the browser, and a media type with no extractor never produces one.",
+        "description": "A resource's coordinate map, a stored decline, or a named reason there is none (SMELTER-OWNS-OCR P1). Never null: absence used to be a bare null covering four different facts — barrier expired, settled-skipped, no content identity, fold disposed — two of which a caller should retry and two of which it should not.",
         "properties": {
           "correlationId": {
             "type": "string"
           },
           "response": {
-            "nullable": true,
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/ExtractionOutcome"
-              }
-            ]
+            "$ref": "#/components/schemas/AnchoredTextAnswer"
           }
         },
         "required": [
@@ -2786,20 +2785,46 @@
           "response"
         ]
       },
-      "BrowseAnchoredTextByChecksumRequest": {
+      "AnchoredTextAnswer": {
+        "description": "What a reader gets when it asks for a resource's coordinate map: the map, a stored decline, or a named absence.\n\nDistinct from `ExtractionOutcome` on purpose. That type is what the STORE holds and what an extractor RETURNS — neither of which can ever be 'not yet'. This is the read answer, which can, so widening ExtractionOutcome itself would have put an impossible state into the store's own type.\n\nFlat, one discriminant: every member carries `kind`, rather than nesting an outcome inside a status envelope and giving the wire two `kind` fields at different depths.",
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/ExtractedText"
+          },
+          {
+            "$ref": "#/components/schemas/ExtractionDeclined"
+          },
+          {
+            "$ref": "#/components/schemas/AnchoredTextAbsent"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "kind",
+          "mapping": {
+            "extracted": "#/components/schemas/ExtractedText",
+            "declined": "#/components/schemas/ExtractionDeclined",
+            "not-yet": "#/components/schemas/AnchoredTextAbsent",
+            "no-map": "#/components/schemas/AnchoredTextAbsent",
+            "unknown": "#/components/schemas/AnchoredTextAbsent"
+          }
+        }
+      },
+      "AnchoredTextAbsent": {
         "type": "object",
-        "description": "Request the stored extraction outcome for a content identity the caller already holds — the detection workers' read-through cache consult (ANCHORED-TEXT-TO-SMELTER P2). A hit — success or decline — is served whole and the caller skips extraction; null is a miss and the caller extracts locally. Read-only: the Smelter is the sole writer and never answers over this channel.",
+        "description": "There is no coordinate map to serve, and WHY — the distinction a bare null could not carry (SMELTER-OWNS-OCR P1).\n\nOne member covers all three absences because none carries a payload; `kind` alone is the fact. Retryability is legible from the name, deliberately: a caller must not need a lookup table to decide whether to come back.",
         "properties": {
-          "correlationId": {
-            "type": "string"
-          },
-          "checksum": {
-            "type": "string"
+          "kind": {
+            "type": "string",
+            "enum": [
+              "not-yet",
+              "no-map",
+              "unknown"
+            ],
+            "description": "Discriminant, sharing the `kind` field with the ExtractedText/ExtractionDeclined members so the whole answer is one flat union (D6).\n\n`not-yet` — the Smelter has not settled this content generation: the settle barrier expired, the progress fold was disposed, or it settled indexed and the artifact is missing (the reconcile planner's third drift class, which heals). RETRY.\n\n`no-map` — the Smelter settled this resource as skipped: its media type derives no geometry, so a map will never exist. TERMINAL.\n\n`unknown` — no content identity to look up: the resource is not in the view store, or its primary representation carries no checksum. TERMINAL."
           }
         },
         "required": [
-          "correlationId",
-          "checksum"
+          "kind"
         ]
       },
       "BrowseResourceRequest": {
@@ -2951,6 +2976,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 +3034,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 +3858,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 +3870,10 @@
             "minimum": 0,
             "maximum": 100
           }
-        }
+        },
+        "required": [
+          "correlationId"
+        ]
       },
       "GatherResourceComplete": {
         "type": "object",
@@ -4584,21 +4627,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 +4869,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 +4897,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 +5106,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 +5927,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.29",
+  "version": "0.5.31",
   "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.29",
-    "@semiont/make-meaning": "0.5.29",
-    "@semiont/observability": "0.5.29",
+    "@semiont/core": "0.5.31",
+    "@semiont/make-meaning": "0.5.31",
+    "@semiont/observability": "0.5.31",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "argon2": "^0.45.1",
@@ -40,6 +40,6 @@
     "jsonwebtoken": "^9.0.2",
     "prisma": "^7.10.0",
     "winston": "^3.19.0",
-    "zod": "^4.4.3"
+    "zod": "^4.5.4"
   }
 }