@semiont/backend 0.5.5 → 0.5.7

package/dist/index.js

@@ -3,7 +3,7 @@ import winston from 'winston';
 import { recordSubscriberConnect, recordSubscriberDisconnect, withTraceparent, withSpan, recordBusEmit, SpanKind, injectTraceparent, getLogTraceContext } from '@semiont/observability';
 import { z } from 'zod';
 import jwt from 'jsonwebtoken';
-import { email, userId, googleCredential, agentToDid, EventBus, accessToken, userToDid, resourceId, CHANNEL_SCHEMAS, busLog, getPrimaryMediaType, decodeRepresentation } from '@semiont/core';
+import { email, userId, googleCredential, agentToDid, EventBus, accessToken, userToDid, resourceId, CHANNEL_SCHEMAS, busLog, baseMediaType, isSupportedMediaType, getPrimaryMediaType } from '@semiont/core';
 import { cors } from 'hono/cors';
 import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
@@ -10823,26 +10823,6 @@ var openapi_default = {
             $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: {
@@ -10856,29 +10836,6 @@ var openapi_default = {
             required: [
               "content"
             ]
-          },
-          suggestedResolution: {
-            type: "object",
-            properties: {
-              resourceId: {
-                type: "string"
-              },
-              resourceName: {
-                type: "string"
-              },
-              confidence: {
-                type: "number"
-              },
-              reasoning: {
-                type: "string"
-              }
-            },
-            required: [
-              "resourceId",
-              "resourceName",
-              "confidence",
-              "reasoning"
-            ]
           }
         },
         required: [
@@ -11387,9 +11344,78 @@ var openapi_default = {
       },
       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 \u2014 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 \u2014 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: {
@@ -11692,18 +11718,13 @@ var openapi_default = {
             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: {
@@ -17187,9 +17208,11 @@ exchangeRouter.post("/api/moderate/exchange/import", async (c) => {
         send({
           phase: "complete",
           result: {
-            resourcesCreated: result.resourcesCreated,
-            annotationsCreated: result.annotationsCreated,
-            entityTypesAdded: result.entityTypesAdded
+            stats: {
+              resourcesCreated: result.resourcesCreated,
+              annotationsCreated: result.annotationsCreated,
+              entityTypesAdded: result.entityTypesAdded
+            }
           }
         });
       } catch (err) {
@@ -17214,93 +17237,6 @@ function createResourceRouter() {
   router.use("/resources/*", authMiddleware);
   return router;
 }
-
-// ../../packages/content/dist/index.js
-var MIME_TO_EXTENSION = {
-  // Text formats
-  "text/plain": ".txt",
-  "text/markdown": ".md",
-  "text/html": ".html",
-  "text/css": ".css",
-  "text/csv": ".csv",
-  "text/xml": ".xml",
-  // Application formats - structured data
-  "application/json": ".json",
-  "application/xml": ".xml",
-  "application/yaml": ".yaml",
-  "application/x-yaml": ".yaml",
-  // Application formats - documents
-  "application/pdf": ".pdf",
-  "application/msword": ".doc",
-  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
-  "application/vnd.ms-excel": ".xls",
-  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
-  "application/vnd.ms-powerpoint": ".ppt",
-  "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
-  // Application formats - archives
-  "application/zip": ".zip",
-  "application/gzip": ".gz",
-  "application/x-tar": ".tar",
-  "application/x-7z-compressed": ".7z",
-  // Application formats - executables/binaries
-  "application/octet-stream": ".bin",
-  "application/wasm": ".wasm",
-  // Image formats
-  "image/png": ".png",
-  "image/jpeg": ".jpg",
-  "image/gif": ".gif",
-  "image/webp": ".webp",
-  "image/svg+xml": ".svg",
-  "image/bmp": ".bmp",
-  "image/tiff": ".tiff",
-  "image/x-icon": ".ico",
-  // Audio formats
-  "audio/mpeg": ".mp3",
-  "audio/wav": ".wav",
-  "audio/ogg": ".ogg",
-  "audio/webm": ".webm",
-  "audio/aac": ".aac",
-  "audio/flac": ".flac",
-  // Video formats
-  "video/mp4": ".mp4",
-  "video/mpeg": ".mpeg",
-  "video/webm": ".webm",
-  "video/ogg": ".ogv",
-  "video/quicktime": ".mov",
-  "video/x-msvideo": ".avi",
-  // Programming languages
-  "text/javascript": ".js",
-  "application/javascript": ".js",
-  "text/x-typescript": ".ts",
-  "application/typescript": ".ts",
-  "text/x-python": ".py",
-  "text/x-java": ".java",
-  "text/x-c": ".c",
-  "text/x-c++": ".cpp",
-  "text/x-csharp": ".cs",
-  "text/x-go": ".go",
-  "text/x-rust": ".rs",
-  "text/x-ruby": ".rb",
-  "text/x-php": ".php",
-  "text/x-swift": ".swift",
-  "text/x-kotlin": ".kt",
-  "text/x-shell": ".sh",
-  // Font formats
-  "font/woff": ".woff",
-  "font/woff2": ".woff2",
-  "font/ttf": ".ttf",
-  "font/otf": ".otf"
-};
-function getExtensionForMimeType(mediaType) {
-  const normalized = mediaType.toLowerCase().split(";")[0].trim();
-  const extension = MIME_TO_EXTENSION[normalized];
-  return extension || ".dat";
-}
-function deriveStorageUri(name, format) {
-  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-  const ext = getExtensionForMimeType(format);
-  return `file://${slug}${ext}`;
-}
 function registerCreateResource(router) {
   router.post("/resources", async (c) => {
     const user = c.get("user");
@@ -17320,9 +17256,15 @@ function registerCreateResource(router) {
     const generationPrompt = formData.get("generationPrompt");
     const generatorStr = formData.get("generator");
     const isDraftStr = formData.get("isDraft");
-    if (!name || !file || !formatRaw) {
+    if (!name || !file || !formatRaw || !storageUri) {
+      throw new HTTPException(400, {
+        message: "Missing required fields: name, file, format, storageUri"
+      });
+    }
+    const formatBase = baseMediaType(formatRaw);
+    if (!isSupportedMediaType(formatBase)) {
       throw new HTTPException(400, {
-        message: "Missing required fields: name, file, format"
+        message: `Unsupported media type: ${formatBase}`
       });
     }
     const format = formatRaw;
@@ -17349,13 +17291,12 @@ function registerCreateResource(router) {
           const arrayBuffer = await file.arrayBuffer();
           const contentBuffer = Buffer.from(arrayBuffer);
           const { knowledgeSystem: { kb } } = c.get("makeMeaning");
-          const resolvedUri = storageUri || deriveStorageUri(name, format);
-          const stored = await kb.content.store(contentBuffer, resolvedUri);
+          const stored = await kb.content.store(contentBuffer, storageUri);
           const eventBus2 = c.get("eventBus");
           return ResourceOperations.createResource(
             {
               name,
-              storageUri: resolvedUri,
+              storageUri,
               contentChecksum: stored.checksum,
               byteSize: stored.byteSize,
               format,
@@ -17410,98 +17351,46 @@ async function eventBusRequest(eventBus2, requestEvent, payload, successEvent, f
 // src/routes/resources/routes/get-uri.ts
 init_logger();
 var getRouteLogger3 = () => getLogger().child({ component: "get-resource-uri" });
-function registerGetResourceUri(router) {
-  router.get("/api/resources/:id", async (c) => {
-    const { id } = c.req.param();
-    let acceptHeader = c.req.header("Accept") || "*/*";
-    acceptHeader = acceptHeader.split(",").map((t) => t.trim()).filter((t) => t !== "application/ld+json" && t !== "application/json").join(", ") || "*/*";
-    busLog("GET", "content", { resourceId: id, accept: acceptHeader });
-    const traceparent = c.req.header("traceparent");
-    const tracestate = c.req.header("tracestate");
-    const carrier = traceparent ? tracestate ? { traceparent, tracestate } : { traceparent } : void 0;
-    return withTraceparent(
-      carrier,
-      () => withSpan(
-        "content.get.server",
-        async () => {
-          const { knowledgeSystem: { kb } } = c.get("makeMeaning");
-          let resource;
-          try {
-            resource = await ResourceContext.getResourceMetadata(resourceId(id), kb);
-          } catch {
-            throw new HTTPException(500, { message: "Failed to retrieve resource" });
-          }
-          if (!resource) throw new HTTPException(404, { message: "Resource not found" });
-          if (!resource.storageUri) throw new HTTPException(404, { message: "Resource representation not found" });
-          const content = await kb.content.retrieve(resource.storageUri);
-          if (!content) throw new HTTPException(404, { message: "Resource representation not found" });
-          const mediaType = getPrimaryMediaType(resource);
-          c.header("Cache-Control", "public, max-age=31536000, immutable");
-          if (mediaType) c.header("Content-Type", mediaType);
-          if (mediaType?.startsWith("image/") || mediaType === "application/pdf") {
-            return c.newResponse(new Uint8Array(content), 200, { "Content-Type": mediaType });
-          }
-          return c.text(decodeRepresentation(content, mediaType || "text/plain"));
-        },
-        {
-          kind: SpanKind.SERVER,
-          attrs: { "resource.id": id, "http.accept": acceptHeader }
-        }
-      )
-    );
+function traceCarrier(c) {
+  const traceparent = c.req.header("traceparent");
+  const tracestate = c.req.header("tracestate");
+  return traceparent ? tracestate ? { traceparent, tracestate } : { traceparent } : void 0;
+}
+async function loadRepresentation(id, kb) {
+  let resource;
+  try {
+    resource = await ResourceContext.getResourceMetadata(resourceId(id), kb);
+  } catch (error) {
+    getRouteLogger3().error("Failed to get resource metadata", {
+      resourceId: id,
+      error: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : void 0
+    });
+    throw new HTTPException(500, { message: "Failed to retrieve resource" });
+  }
+  if (!resource) {
+    throw new HTTPException(404, { message: "Resource not found" });
+  }
+  if (!resource.storageUri) {
+    throw new HTTPException(404, { message: "Resource representation not found" });
+  }
+  const content = await kb.content.retrieve(resource.storageUri);
+  if (!content) {
+    throw new HTTPException(404, { message: "Resource representation not found" });
+  }
+  return { content, mediaType: getPrimaryMediaType(resource) };
+}
+function pipeRepresentation(c, content, mediaType) {
+  return c.newResponse(new Uint8Array(content), 200, {
+    "Content-Type": mediaType || "application/octet-stream"
   });
-  router.get("/resources/:id", async (c) => {
+}
+function describedByLink(id) {
+  return `</resources/${id}/jsonld>; rel="describedby"; type="application/ld+json"`;
+}
+function registerGetResourceUri(router) {
+  router.get("/resources/:id/jsonld", async (c) => {
     const { id } = c.req.param();
-    const acceptHeader = c.req.header("Accept") || "application/ld+json";
-    if (acceptHeader.includes("text/") || acceptHeader.includes("image/") || acceptHeader.includes("application/pdf")) {
-      busLog("GET", "content", { resourceId: id, accept: acceptHeader });
-      const traceparent = c.req.header("traceparent");
-      const tracestate = c.req.header("tracestate");
-      const carrier = traceparent ? tracestate ? { traceparent, tracestate } : { traceparent } : void 0;
-      return withTraceparent(
-        carrier,
-        () => withSpan(
-          "content.get.server",
-          async () => {
-            const { knowledgeSystem: { kb } } = c.get("makeMeaning");
-            let resource;
-            try {
-              resource = await ResourceContext.getResourceMetadata(resourceId(id), kb);
-            } catch (error) {
-              getRouteLogger3().error("Failed to get resource metadata", {
-                resourceId: id,
-                error: error instanceof Error ? error.message : String(error),
-                stack: error instanceof Error ? error.stack : void 0
-              });
-              throw new HTTPException(500, { message: "Failed to retrieve resource" });
-            }
-            if (!resource) {
-              throw new HTTPException(404, { message: "Resource not found" });
-            }
-            if (!resource.storageUri) {
-              throw new HTTPException(404, { message: "Resource representation not found" });
-            }
-            const content = await kb.content.retrieve(resource.storageUri);
-            if (!content) {
-              throw new HTTPException(404, { message: "Resource representation not found" });
-            }
-            const mediaType = getPrimaryMediaType(resource);
-            if (mediaType) {
-              c.header("Content-Type", mediaType);
-            }
-            if (mediaType?.startsWith("image/") || mediaType === "application/pdf") {
-              return c.newResponse(new Uint8Array(content), 200, { "Content-Type": mediaType });
-            } else {
-              return c.text(decodeRepresentation(content, mediaType || "text/plain"));
-            }
-          },
-          {
-            kind: SpanKind.SERVER,
-            attrs: { "resource.id": id, "http.accept": acceptHeader }
-          }
-        )
-      );
-    }
     const eventBus2 = c.get("eventBus");
     const correlationId = crypto.randomUUID();
     try {
@@ -17512,8 +17401,11 @@ function registerGetResourceUri(router) {
         "browse:resource-result",
         "browse:resource-failed"
       );
-      c.header("Content-Type", "application/ld+json; charset=utf-8");
-      return c.json(response);
+      return c.json(response, 200, {
+        "Content-Type": "application/ld+json; charset=utf-8",
+        // Live data: annotations and inbound references change.
+        "Cache-Control": "no-cache"
+      });
     } catch (error) {
       if (error instanceof Error) {
         if (error.message === "Resource not found") {
@@ -17526,6 +17418,42 @@ function registerGetResourceUri(router) {
       throw error;
     }
   });
+  router.get("/resources/:id", async (c) => {
+    const { id } = c.req.param();
+    busLog("GET", "content", { resourceId: id });
+    return withTraceparent(
+      traceCarrier(c),
+      () => withSpan(
+        "content.get.server",
+        async () => {
+          const { knowledgeSystem: { kb } } = c.get("makeMeaning");
+          const { content, mediaType } = await loadRepresentation(id, kb);
+          c.header("Cache-Control", "private, max-age=31536000, immutable");
+          c.header("Link", describedByLink(id));
+          return pipeRepresentation(c, content, mediaType);
+        },
+        { kind: SpanKind.SERVER, attrs: { "resource.id": id } }
+      )
+    );
+  });
+  router.get("/api/resources/:id", async (c) => {
+    const { id } = c.req.param();
+    busLog("GET", "content", { resourceId: id });
+    return withTraceparent(
+      traceCarrier(c),
+      () => withSpan(
+        "content.get.server",
+        async () => {
+          const { knowledgeSystem: { kb } } = c.get("makeMeaning");
+          const { content, mediaType } = await loadRepresentation(id, kb);
+          c.header("Cache-Control", "public, max-age=31536000, immutable");
+          c.header("Link", describedByLink(id));
+          return pipeRepresentation(c, content, mediaType);
+        },
+        { kind: SpanKind.SERVER, attrs: { "resource.id": id } }
+      )
+    );
+  });
 }
 
 // src/routes/resources/index.ts