@semiont/backend 0.5.6 → 0.5.8

package/dist/openapi.json

@@ -1401,7 +1401,7 @@
                   },
                   "storageUri": {
                     "type": "string",
-                    "description": "Where the content has been / should be placed (file://... for local). If omitted, derived from name + format."
+                    "description": "Where the content lives (file://... for local). Required — the client names the location; the server does not derive one."
                   },
                   "language": {
                     "type": "string",
@@ -1435,7 +1435,8 @@
                 "required": [
                   "name",
                   "file",
-                  "format"
+                  "format",
+                  "storageUri"
                 ]
               }
             }
@@ -1453,7 +1454,7 @@
             }
           },
           "400": {
-            "description": "Missing required fields (name, file, or format)",
+            "description": "Missing required fields (name, file, format, or storageUri), or the format's base MIME type is not a SupportedMediaType. The error message names the offending type.",
             "content": {
               "application/json": {
                 "schema": {
@@ -1477,8 +1478,8 @@
     },
     "/resources/{id}": {
       "get": {
-        "summary": "Get a resource (content-negotiated)",
-        "description": "Content negotiation via the Accept header:\n- application/ld+json (default) — returns JSON-LD metadata including all annotations + inbound entity references\n- text/* or image/* or application/pdf — returns the raw representation bytes\n\nBinary payloads flow directly from the content store; metadata payloads go through the bus gateway.",
+        "summary": "Get a resource's stored representation (the pipe)",
+        "description": "Returns the stored representation's bytes, verbatim, with the stored media type in Content-Type (`application/octet-stream` when the stored metadata carries none). The Accept header is never read: there is no content negotiation and no transcoding, so the served bytes always hash to the representation's registered checksum.\n\nThe resource's JSON-LD description (descriptor + annotations + inbound entity references) lives at GET /resources/{id}/jsonld; every content response advertises it via a `Link: rel=\"describedby\"` header.\n\nContent is immutable (checksum-addressed), and this route is bearer-authenticated, so responses carry `Cache-Control: private, max-age=31536000, immutable`.",
         "tags": [
           "Resources"
         ],
@@ -1495,48 +1496,21 @@
             "schema": {
               "type": "string"
             }
-          },
-          {
-            "name": "Accept",
-            "in": "header",
-            "required": false,
-            "schema": {
-              "type": "string"
-            },
-            "description": "application/ld+json for metadata, or a text/image/pdf media type for raw content"
           }
         ],
         "responses": {
           "200": {
-            "description": "Resource content or metadata, depending on Accept",
-            "content": {
-              "application/ld+json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GetResourceResponse"
-                }
-              },
-              "text/plain": {
-                "schema": {
-                  "type": "string"
-                }
-              },
-              "text/markdown": {
+            "description": "The stored representation's bytes, verbatim",
+            "headers": {
+              "Link": {
                 "schema": {
                   "type": "string"
-                }
-              },
-              "text/html": {
-                "schema": {
-                  "type": "string"
-                }
-              },
-              "image/*": {
-                "schema": {
-                  "type": "string",
-                  "format": "binary"
-                }
-              },
-              "application/pdf": {
+                },
+                "description": "`</resources/{id}/jsonld>; rel=\"describedby\"; type=\"application/ld+json\"` — where to dereference the resource's JSON-LD description"
+              }
+            },
+            "content": {
+              "*/*": {
                 "schema": {
                   "type": "string",
                   "format": "binary"
@@ -1545,7 +1519,7 @@
             }
           },
           "404": {
-            "description": "Resource not found",
+            "description": "Resource or representation not found",
             "content": {
               "application/json": {
                 "schema": {
@@ -1563,6 +1537,52 @@
                 }
               }
             }
+          }
+        }
+      }
+    },
+    "/resources/{id}/jsonld": {
+      "get": {
+        "summary": "Get a resource's JSON-LD description",
+        "description": "The dereferenceable linked-data description of the resource: its descriptor plus all annotations and inbound entity references, assembled via the bus gateway. This is the target of the `Link: rel=\"describedby\"` header that GET /resources/{id} sends with every content response.\n\nLive data — annotations and references change — so responses carry `Cache-Control: no-cache`, in contrast to the immutable content at GET /resources/{id}.",
+        "tags": [
+          "Resources"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The resource's JSON-LD description",
+            "content": {
+              "application/ld+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetResourceResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           },
           "504": {
             "description": "Request timed out (bus gateway)",
@@ -1579,8 +1599,8 @@
     },
     "/api/resources/{id}": {
       "get": {
-        "summary": "Get raw resource content (browser-friendly alias)",
-        "description": "Browser-friendly alternative to GET /resources/{id} that always returns the raw representation, never JSON-LD. Used by `<img>` / PDF.js / `<video>` tags and anywhere an httpOnly cookie is the only feasible auth vector. Behaves like GET /resources/{id} with JSON-LD stripped from the Accept header before content negotiation.\n\nSets long-lived immutable Cache-Control (content is addressed by checksum upstream, so bytes never change for a given resource id).",
+        "summary": "Get a resource's stored representation (browser-friendly alias)",
+        "description": "Identical pipe to GET /resources/{id} — verbatim bytes, stored media type in Content-Type, Accept never read. Exists only as the auth affordance for `<img>` / PDF.js / download links, which cannot carry Authorization headers: the `?token=` media token or the httpOnly semiont-token cookie ride along automatically.\n\nResponses carry `Cache-Control: public, max-age=31536000, immutable` — `public` is safe here, unlike the bearer-authenticated main route, because the `?token=` is part of the cache key.",
         "tags": [
           "Resources"
         ],
@@ -1601,30 +1621,17 @@
         ],
         "responses": {
           "200": {
-            "description": "Raw representation bytes with appropriate Content-Type",
-            "content": {
-              "text/plain": {
-                "schema": {
-                  "type": "string"
-                }
-              },
-              "text/markdown": {
-                "schema": {
-                  "type": "string"
-                }
-              },
-              "text/html": {
+            "description": "The stored representation's bytes, verbatim",
+            "headers": {
+              "Link": {
                 "schema": {
                   "type": "string"
-                }
-              },
-              "image/*": {
-                "schema": {
-                  "type": "string",
-                  "format": "binary"
-                }
-              },
-              "application/pdf": {
+                },
+                "description": "`</resources/{id}/jsonld>; rel=\"describedby\"; type=\"application/ld+json\"` — where to dereference the resource's JSON-LD description"
+              }
+            },
+            "content": {
+              "*/*": {
                 "schema": {
                   "type": "string",
                   "format": "binary"
@@ -2158,26 +2165,6 @@
             "$ref": "#/components/schemas/GatheredContext",
             "description": "Gathered context for this annotation"
           },
-          "sourceContext": {
-            "type": "object",
-            "description": "DEPRECATED: Use 'context' instead. Legacy source context format.",
-            "properties": {
-              "before": {
-                "type": "string"
-              },
-              "selected": {
-                "type": "string"
-              },
-              "after": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "before",
-              "selected",
-              "after"
-            ]
-          },
           "targetContext": {
             "type": "object",
             "properties": {
@@ -2191,29 +2178,6 @@
             "required": [
               "content"
             ]
-          },
-          "suggestedResolution": {
-            "type": "object",
-            "properties": {
-              "resourceId": {
-                "type": "string"
-              },
-              "resourceName": {
-                "type": "string"
-              },
-              "confidence": {
-                "type": "number"
-              },
-              "reasoning": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "resourceId",
-              "resourceName",
-              "confidence",
-              "reasoning"
-            ]
           }
         },
         "required": [
@@ -2722,9 +2686,78 @@
       },
       "ContentFormat": {
         "type": "string",
-        "description": "Content format as MIME type, optionally with charset parameter. Values include: text/plain, text/plain; charset=utf-8, text/plain; charset=iso-8859-1, text/markdown, text/markdown; charset=windows-1252, image/png, image/jpeg, application/pdf",
+        "description": "Content format as a MIME type, optionally with parameters. The base type (everything before the first ';') MUST be a SupportedMediaType; parameters such as charset are preserved as metadata. Semantic validation happens in code at the create/yield boundary — there is deliberately no pattern here, the vocabulary lives in SupportedMediaType. Examples: text/plain, text/plain; charset=iso-8859-1, text/markdown; charset=windows-1252, image/png, application/pdf",
         "example": "text/plain; charset=utf-8"
       },
+      "SupportedMediaType": {
+        "type": "string",
+        "description": "Base MIME types (no parameters) admitted by Semiont. Membership is the create/yield gate — every member is storable, nameable, and uploadable. What more the system can do with a type (render, annotate, extract text, author) is curated per type in @semiont/core's media-type registry, which is keyed by this enum.",
+        "enum": [
+          "text/plain",
+          "text/markdown",
+          "text/html",
+          "text/css",
+          "text/csv",
+          "text/xml",
+          "application/json",
+          "application/xml",
+          "application/yaml",
+          "application/x-yaml",
+          "application/pdf",
+          "application/msword",
+          "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+          "application/vnd.ms-excel",
+          "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+          "application/vnd.ms-powerpoint",
+          "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+          "application/zip",
+          "application/gzip",
+          "application/x-tar",
+          "application/x-7z-compressed",
+          "application/octet-stream",
+          "application/wasm",
+          "image/png",
+          "image/jpeg",
+          "image/gif",
+          "image/webp",
+          "image/svg+xml",
+          "image/bmp",
+          "image/tiff",
+          "image/x-icon",
+          "video/mp4",
+          "video/mpeg",
+          "video/webm",
+          "video/ogg",
+          "video/quicktime",
+          "video/x-msvideo",
+          "audio/mpeg",
+          "audio/wav",
+          "audio/ogg",
+          "audio/webm",
+          "audio/aac",
+          "audio/flac",
+          "text/javascript",
+          "application/javascript",
+          "text/x-typescript",
+          "application/typescript",
+          "text/x-python",
+          "text/x-java",
+          "text/x-c",
+          "text/x-c++",
+          "text/x-csharp",
+          "text/x-go",
+          "text/x-rust",
+          "text/x-ruby",
+          "text/x-php",
+          "text/x-swift",
+          "text/x-kotlin",
+          "text/x-shell",
+          "font/woff",
+          "font/woff2",
+          "font/ttf",
+          "font/otf"
+        ]
+      },
       "ContextualSummaryResponse": {
         "type": "object",
         "properties": {
@@ -3027,18 +3060,13 @@
             "type": "integer",
             "description": "Monotonic position in the event log (ordering authority)"
           },
-          "streamPosition": {
-            "type": "integer",
-            "description": "Byte offset in the JSONL file"
-          },
           "correlationId": {
             "type": "string",
             "description": "Optional correlation id propagated from a command. Lets clients match command-result events back to the POST that initiated them. Set by EventStore.appendEvent's options when a route handler passes one through."
           }
         },
         "required": [
-          "sequenceNumber",
-          "streamPosition"
+          "sequenceNumber"
         ]
       },
       "SelectionData": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/backend",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "type": "module",
   "description": "Semiont backend server - pre-built for npm consumption",
   "main": "dist/index.js",
@@ -15,24 +15,6 @@
   "scripts": {
     "start": "node dist/index.js"
   },
-  "dependencies": {
-    "@hono/node-server": "^1.17.1",
-    "@hono/swagger-ui": "^0.6.1",
-    "@prisma/adapter-pg": "^7.5.0",
-    "@prisma/client": "^7.5.0",
-    "@semiont/core": "^0.5.6",
-    "@semiont/event-sourcing": "^0.5.6",
-    "@semiont/jobs": "^0.5.6",
-    "@semiont/make-meaning": "^0.5.6",
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
-    "argon2": "^0.44.0",
-    "hono": "^4.8.10",
-    "jsonwebtoken": "^9.0.2",
-    "prisma": "^7.5.0",
-    "winston": "^3.19.0",
-    "zod": "^4.0.0"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -41,5 +23,22 @@
     "url": "https://github.com/The-AI-Alliance/semiont.git",
     "directory": "apps/backend"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@hono/node-server": "^2.0.4",
+    "@hono/swagger-ui": "^0.6.1",
+    "@prisma/adapter-pg": "^7.8.0",
+    "@prisma/client": "^7.8.0",
+    "@semiont/core": "0.5.8",
+    "@semiont/make-meaning": "0.5.8",
+    "@semiont/observability": "0.5.8",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "argon2": "^0.44.0",
+    "hono": "^4.12.25",
+    "jsonwebtoken": "^9.0.2",
+    "prisma": "^7.8.0",
+    "winston": "^3.19.0",
+    "zod": "^4.4.3"
+  }
 }