@semiont/backend 0.5.2 → 0.5.4

package/dist/openapi.json

@@ -256,10 +256,10 @@
         }
       }
     },
-    "/api/tokens/worker": {
+    "/api/tokens/agent": {
       "post": {
-        "summary": "Worker Token Exchange",
-        "description": "Exchange a shared secret for a bearer JWT. Used by workers and actors connecting to the EventBus.",
+        "summary": "Software-Agent Token Exchange",
+        "description": "Exchange the shared secret plus an inference (provider, model) pair for a bearer JWT issued for that agent identity. Used by worker processes that emit on behalf of one or more software peers.\n\nThe issued JWT carries the agent's DID (shape `did:web:<host>:agents:<provider>:<model>`); the bus stamps that DID onto `_userId` so events the agent emits attribute to the agent rather than to a generic worker pool.",
         "tags": [
           "Authentication"
         ],
@@ -273,11 +273,21 @@
                 "properties": {
                   "secret": {
                     "type": "string",
-                    "description": "The shared worker secret (SEMIONT_WORKER_SECRET)"
+                    "description": "The shared secret (SEMIONT_WORKER_SECRET)"
+                  },
+                  "provider": {
+                    "type": "string",
+                    "description": "Inference provider (e.g. ollama, anthropic)"
+                  },
+                  "model": {
+                    "type": "string",
+                    "description": "Model identifier (e.g. gemma2:27b, claude-3-5-sonnet)"
                   }
                 },
                 "required": [
-                  "secret"
+                  "secret",
+                  "provider",
+                  "model"
                 ]
               }
             }
@@ -294,17 +304,32 @@
                     "token": {
                       "type": "string",
                       "description": "Bearer JWT for subsequent authenticated requests"
+                    },
+                    "did": {
+                      "type": "string",
+                      "description": "DID of the software-agent identity the token is acting as"
                     }
                   },
                   "required": [
-                    "token"
+                    "token",
+                    "did"
                   ]
                 }
               }
             }
           },
+          "400": {
+            "description": "Missing or invalid request fields",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
           "401": {
-            "description": "Invalid worker secret",
+            "description": "Invalid agent secret",
             "content": {
               "application/json": {
                 "schema": {
@@ -314,7 +339,7 @@
             }
           },
           "503": {
-            "description": "Worker authentication not configured",
+            "description": "Agent authentication not configured",
             "content": {
               "application/json": {
                 "schema": {
@@ -1386,10 +1411,6 @@
                     "type": "string",
                     "description": "JSON-stringified array of entity type names"
                   },
-                  "creationMethod": {
-                    "type": "string",
-                    "description": "How this resource was created (api, ui, upload, reference, cli, clone, generated)"
-                  },
                   "sourceAnnotationId": {
                     "type": "string",
                     "description": "For AI-generated resources: the annotation that triggered generation. Nested into generatedFrom.annotationId on the persisted event."
@@ -1870,48 +1891,103 @@
         ]
       },
       "Agent": {
-        "type": "object",
-        "description": "Minimal Person/Organization for attribution (W3C PROV compatible)",
-        "additionalProperties": true,
-        "properties": {
-          "@id": {
-            "type": "string",
-            "format": "uri",
-            "description": "Unique identifier for the agent"
-          },
-          "@type": {
-            "description": "Type(s) of agent (Person, Organization, Software)",
-            "oneOf": [
-              {
+        "description": "Web Annotation / W3C PROV Agent. Discriminated by @type — Person, Organization, or Software. Each branch carries fields appropriate to its kind. Software peers are first-class participants, not a sub-class of Person.",
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "@type": {
+                "type": "string",
+                "const": "Person"
+              },
+              "@id": {
+                "type": "string",
+                "format": "uri",
+                "description": "DID-shaped identifier (e.g. did:web:host:users:email%40host)"
+              },
+              "name": {
+                "type": "string",
+                "description": "Display name"
+              },
+              "nickname": {
                 "type": "string"
               },
-              {
-                "type": "array",
-                "items": {
-                  "type": "string"
-                },
-                "minItems": 1
+              "email": {
+                "type": "string"
+              },
+              "email_sha1": {
+                "type": "string"
+              },
+              "homepage": {
+                "type": "string"
               }
+            },
+            "required": [
+              "@type",
+              "name"
             ]
           },
-          "name": {
-            "type": "string"
-          },
-          "nickname": {
-            "type": "string"
-          },
-          "email": {
-            "type": "string"
-          },
-          "email_sha1": {
-            "type": "string"
+          {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "@type": {
+                "type": "string",
+                "const": "Organization"
+              },
+              "@id": {
+                "type": "string",
+                "format": "uri"
+              },
+              "name": {
+                "type": "string"
+              },
+              "homepage": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "@type",
+              "name"
+            ]
           },
-          "homepage": {
-            "type": "string"
+          {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "@type": {
+                "type": "string",
+                "const": "Software"
+              },
+              "@id": {
+                "type": "string",
+                "format": "uri",
+                "description": "DID-shaped identifier (e.g. did:web:host:agents:provider:model)"
+              },
+              "name": {
+                "type": "string",
+                "description": "Stable human-friendly label. Not parsed; UI composes display from structured fields."
+              },
+              "provider": {
+                "type": "string",
+                "description": "Inference provider (e.g. ollama, anthropic)"
+              },
+              "model": {
+                "type": "string",
+                "description": "Model identifier (e.g. gemma2:27b, claude-3-5-sonnet)"
+              },
+              "parameters": {
+                "type": "object",
+                "additionalProperties": true,
+                "description": "Inference parameters (temperature, maxTokens, systemPrompt, etc.). Runtime metadata, not part of identity."
+              }
+            },
+            "required": [
+              "@type",
+              "name"
+            ]
           }
-        },
-        "required": [
-          "name"
         ]
       },
       "Annotation": {
@@ -1969,7 +2045,8 @@
             "description": "W3C Web Annotation body. Optional per the W3C spec — annotations whose motivation alone is meaningful (highlighting) legitimately omit it. Present values are either a single body or a non-empty array of bodies; the prior empty-array 'stub' branch has been removed (it was a naming lie shared between highlights and never-actually-emitted stub references, and the source of the #651 reference-annotation validator bug)."
           },
           "creator": {
-            "$ref": "#/components/schemas/Agent"
+            "$ref": "#/components/schemas/Agent",
+            "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"
@@ -1978,7 +2055,34 @@
             "type": "string"
           },
           "generator": {
-            "$ref": "#/components/schemas/Agent"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/Agent"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/Agent"
+                },
+                "minItems": 1
+              }
+            ],
+            "description": "Web Annotation generator — the SoftwareAgent that produced the annotation, when software was involved. Absent for purely manual annotations. Single object is the common case; array supports pipelines that combine multiple software peers."
+          },
+          "wasAttributedTo": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/Agent"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/Agent"
+                },
+                "minItems": 1
+              }
+            ],
+            "description": "PROV-O wasAttributedTo — all parties responsible for this annotation. For human-prompted AI work this combines `creator` (the Person) and `generator` (the Software). For purely manual annotations it equals `[creator]`; for autonomous-agent work it equals `[generator]` (and `creator` may be the same Software)."
           }
         },
         "required": [
@@ -3063,18 +3167,6 @@
           "contentByteSize": {
             "type": "integer"
           },
-          "creationMethod": {
-            "type": "string",
-            "enum": [
-              "api",
-              "upload",
-              "ui",
-              "reference",
-              "cli",
-              "clone",
-              "generated"
-            ]
-          },
           "entityTypes": {
             "type": "array",
             "items": {
@@ -3126,8 +3218,7 @@
         "required": [
           "name",
           "format",
-          "contentChecksum",
-          "creationMethod"
+          "contentChecksum"
         ]
       },
       "ResourceClonedPayload": {
@@ -3149,18 +3240,6 @@
           "parentResourceId": {
             "type": "string"
           },
-          "creationMethod": {
-            "type": "string",
-            "enum": [
-              "api",
-              "upload",
-              "ui",
-              "reference",
-              "cli",
-              "clone",
-              "generated"
-            ]
-          },
           "entityTypes": {
             "type": "array",
             "items": {
@@ -3175,8 +3254,7 @@
           "name",
           "format",
           "contentChecksum",
-          "parentResourceId",
-          "creationMethod"
+          "parentResourceId"
         ]
       },
       "ResourceUpdatedPayload": {
@@ -3320,6 +3398,18 @@
           "entityType"
         ]
       },
+      "TagSchemaAddedPayload": {
+        "type": "object",
+        "description": "Payload for frame:tag-schema-added domain event (system-level, no resourceId — fan-out is global to the KB).",
+        "properties": {
+          "schema": {
+            "$ref": "#/components/schemas/TagSchema"
+          }
+        },
+        "required": [
+          "schema"
+        ]
+      },
       "EntityTagChangedPayload": {
         "type": "object",
         "description": "Payload for mark:entity-tag-added and mark:entity-tag-removed domain events",
@@ -3730,6 +3820,20 @@
           "entityReferences"
         ]
       },
+      "GetTagSchemasResponse": {
+        "type": "object",
+        "properties": {
+          "tagSchemas": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TagSchema"
+            }
+          }
+        },
+        "required": [
+          "tagSchemas"
+        ]
+      },
       "GoogleAuthRequest": {
         "type": "object",
         "properties": {
@@ -4290,19 +4394,6 @@
             "type": "boolean",
             "description": "Application-specific: Whether this resource is a draft"
           },
-          "creationMethod": {
-            "type": "string",
-            "enum": [
-              "api",
-              "upload",
-              "ui",
-              "reference",
-              "cli",
-              "clone",
-              "generated"
-            ],
-            "description": "Application-specific: How this resource was created"
-          },
           "sourceAnnotationId": {
             "type": "string",
             "description": "Application-specific: ID of annotation that triggered generation"
@@ -5494,6 +5585,34 @@
           "path"
         ]
       },
+      "BrowseTagSchemasRequest": {
+        "type": "object",
+        "description": "Request to browse registered tag schemas",
+        "properties": {
+          "correlationId": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "correlationId"
+        ]
+      },
+      "BrowseTagSchemasResult": {
+        "type": "object",
+        "description": "Result of browsing tag schemas",
+        "properties": {
+          "correlationId": {
+            "type": "string"
+          },
+          "response": {
+            "$ref": "#/components/schemas/GetTagSchemasResponse"
+          }
+        },
+        "required": [
+          "correlationId",
+          "response"
+        ]
+      },
       "FragmentSelector": {
         "type": "object",
         "description": "W3C Web Annotation FragmentSelector for media fragment identifiers (RFC 3778 for PDFs)",
@@ -6354,6 +6473,22 @@
           "tag"
         ]
       },
+      "FrameAddTagSchemaCommand": {
+        "type": "object",
+        "description": "Bus command to register a tag schema with the KB's runtime registry. Carried on the `frame:add-tag-schema` channel — Frame is the schema-layer flow that owns vocabulary writes. Most-recent registration of a given `schema.id` wins; the projection reflects the latest content. Identical re-registrations are silent; differing content overwrites and logs a warning.",
+        "properties": {
+          "schema": {
+            "$ref": "#/components/schemas/TagSchema"
+          },
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
+          }
+        },
+        "required": [
+          "schema"
+        ]
+      },
       "MarkArchiveCommand": {
         "type": "object",
         "description": "Bus command to archive a resource and optionally remove its file.",
@@ -6890,6 +7025,61 @@
           "value"
         ]
       },
+      "TagCategory": {
+        "type": "object",
+        "description": "A single category within a tag schema (e.g. 'Issue' in IRAC, 'distinguished' in legal-citation-treatment). Each category carries methodology-bound semantics: a name, a description, and examples used in the LLM prompt.",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "examples": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "name",
+          "description",
+          "examples"
+        ]
+      },
+      "TagSchema": {
+        "type": "object",
+        "description": "A structural-analysis schema (e.g. legal-irac, scientific-imrad, argument-toulmin). Defines a methodology framework as an id, name, description, domain hint, and an ordered list of categories. KBs and their skills register schemas with the runtime registry via `frame.addTagSchema(...)` at session start.",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "domain": {
+            "type": "string",
+            "description": "Free-form domain hint (e.g. 'legal', 'scientific', 'general'). Used in the LLM prompt to tune the model's analysis voice. KB authors choose."
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TagCategory"
+            }
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "description",
+          "domain",
+          "tags"
+        ]
+      },
       "YieldCloneCreateCommand": {
         "type": "object",
         "description": "Bus command to create a cloned resource from a clone token.",
@@ -7006,9 +7196,6 @@
               "type": "string"
             }
           },
-          "creationMethod": {
-            "type": "string"
-          },
           "isDraft": {
             "type": "boolean"
           },
@@ -7102,57 +7289,6 @@
           "toUri"
         ]
       },
-      "YieldRequestCommand": {
-        "type": "object",
-        "description": "Bus command to request yield (generation) of a new resource from an annotation.",
-        "properties": {
-          "correlationId": {
-            "type": "string",
-            "description": "Client-supplied id used to match this command to its result event(s) on the events-stream. Generated by the route handler if absent."
-          },
-          "annotationId": {
-            "type": "string"
-          },
-          "resourceId": {
-            "type": "string"
-          },
-          "options": {
-            "type": "object",
-            "properties": {
-              "title": {
-                "type": "string"
-              },
-              "prompt": {
-                "type": "string"
-              },
-              "language": {
-                "type": "string"
-              },
-              "temperature": {
-                "type": "number"
-              },
-              "maxTokens": {
-                "type": "integer"
-              },
-              "context": {
-                "$ref": "#/components/schemas/GatheredContext"
-              },
-              "storageUri": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "title",
-              "storageUri"
-            ]
-          }
-        },
-        "required": [
-          "annotationId",
-          "resourceId",
-          "options"
-        ]
-      },
       "YieldUpdateCommand": {
         "type": "object",
         "description": "Bus command to update a yielded resource's storage content.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/backend",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "type": "module",
   "description": "Semiont backend server - pre-built for npm consumption",
   "main": "dist/index.js",
@@ -20,10 +20,10 @@
     "@hono/swagger-ui": "^0.6.1",
     "@prisma/adapter-pg": "^7.5.0",
     "@prisma/client": "^7.5.0",
-    "@semiont/core": "^0.5.2",
-    "@semiont/event-sourcing": "^0.5.2",
-    "@semiont/jobs": "^0.5.2",
-    "@semiont/make-meaning": "^0.5.2",
+    "@semiont/core": "^0.5.4",
+    "@semiont/event-sourcing": "^0.5.4",
+    "@semiont/jobs": "^0.5.4",
+    "@semiont/make-meaning": "^0.5.4",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "argon2": "^0.44.0",