@jskit-ai/kernel 0.1.55 → 0.1.56

package/server/http/lib/router.js

@@ -2,6 +2,7 @@ import { ensureNonEmptyText, normalizeObject, normalizeText } from "../../../sha
 import { RouteDefinitionError } from "./errors.js";
 import { resolveRouteValidatorOptions } from "./routeValidator.js";
 import { normalizeMiddlewareStack as normalizeSharedMiddlewareStack } from "./routeSupport.js";
+import { normalizeRouteOutputTransform, normalizeRouteTransport } from "./routeTransport.js";
 
 function normalizeMethod(method) {
   return ensureNonEmptyText(method, "route method").toUpperCase();
@@ -79,8 +80,21 @@ class HttpRouter {
     const routeMiddleware = normalizeRouterMiddlewareStack(resolvedOptions.middleware, {
       context: `Route ${input.method} ${input.path} middleware`
     });
-    const routeInput = Object.prototype.hasOwnProperty.call(resolvedOptions, "input") ? resolvedOptions.input : null;
-    const routeOutput = Object.prototype.hasOwnProperty.call(resolvedOptions, "output") ? resolvedOptions.output : null;
+    const routeInput = Object.hasOwn(resolvedOptions, "input") ? resolvedOptions.input : null;
+    const routeOutput = normalizeRouteOutputTransform(
+      Object.hasOwn(resolvedOptions, "output") ? resolvedOptions.output : null,
+      {
+        context: `Route ${input.method} ${input.path} output`,
+        ErrorType: RouteDefinitionError
+      }
+    );
+    const routeTransport = normalizeRouteTransport(
+      Object.hasOwn(resolvedOptions, "transport") ? resolvedOptions.transport : null,
+      {
+        context: `Route ${input.method} ${input.path} transport`,
+        ErrorType: RouteDefinitionError
+      }
+    );
 
     const route = Object.freeze({
       id: normalizeText(resolvedOptions.id),
@@ -89,6 +103,7 @@ class HttpRouter {
       schema: resolvedOptions.schema,
       input: routeInput,
       output: routeOutput,
+      transport: routeTransport,
       config: normalizeObject(resolvedOptions.config),
       auth: resolvedOptions.auth,
       contextPolicy: resolvedOptions.contextPolicy,

package/server/platform/providerRuntime.test.js

@@ -112,17 +112,17 @@ test("createProviderRuntimeFromApp discovers package providers from descriptor d
   }
 });
 
-test("createProviderRuntimeFromApp ignores legacy app local src/server/providers folder", async () => {
-  const appRoot = await createTestAppRoot("kernel-provider-runtime-legacy-app-local-");
+test("createProviderRuntimeFromApp ignores app-local src/server/providers folder", async () => {
+  const appRoot = await createTestAppRoot("kernel-provider-runtime-app-local-");
   try {
     await mkdir(path.join(appRoot, "src", "server", "providers"), { recursive: true });
     await writeFile(
-      path.join(appRoot, "src", "server", "providers", "LegacyProvider.js"),
+      path.join(appRoot, "src", "server", "providers", "IgnoredProvider.js"),
       [
-        "export default class LegacyProvider {",
-        "  static id = \"legacy.app.local\";",
+        "export default class IgnoredProvider {",
+        "  static id = \"ignored.app.local\";",
         "  register(app) {",
-        "    app.instance(\"legacy.value\", true);",
+        "    app.instance(\"ignored.value\", true);",
         "  }",
         "  boot() {}",
         "}"
@@ -139,7 +139,7 @@ test("createProviderRuntimeFromApp ignores legacy app local src/server/providers
     assert.deepEqual(runtime.providerPackageOrder, []);
     assert.equal(runtime.appLocalProviderOrder.length, 0);
     assert.deepEqual(runtime.diagnostics.providerOrder, ["runtime.actions", "runtime.server"]);
-    assert.equal(runtime.app.has("legacy.value"), false);
+    assert.equal(runtime.app.has("ignored.value"), false);
   } finally {
     await rm(appRoot, { recursive: true, force: true });
   }

package/server/runtime/bootBootstrapRoutes.js

@@ -1,18 +1,6 @@
-import { Type } from "typebox";
-import { normalizeObjectInput } from "../../shared/validators/inputNormalization.js";
 import { AUTH_POLICY_PUBLIC } from "../../shared/support/policies.js";
 import { resolveBootstrapPayload } from "../registries/bootstrapPayloadContributorRegistry.js";
 
-const bootstrapQueryValidator = Object.freeze({
-  schema: Type.Object({}, { additionalProperties: true }),
-  normalize: normalizeObjectInput
-});
-
-const bootstrapOutputValidator = Object.freeze({
-  schema: Type.Object({}, { additionalProperties: true }),
-  normalize: normalizeObjectInput
-});
-
 function bootBootstrapRoutes(app) {
   const router = app.make("jskit.http.router");
 
@@ -24,17 +12,13 @@ function bootBootstrapRoutes(app) {
       meta: {
         tags: ["bootstrap"],
         summary: "Resolve app bootstrap payload from registered contributors"
-      },
-      queryValidator: bootstrapQueryValidator,
-      responseValidators: {
-        200: bootstrapOutputValidator
       }
     },
     async function (request, reply) {
       const payload = await resolveBootstrapPayload(app, {
         request,
         reply,
-        query: request.input?.query || {}
+        query: request.query || {}
       });
 
       reply.code(200).send(payload);
@@ -42,4 +26,4 @@ function bootBootstrapRoutes(app) {
   );
 }
 
-export { bootBootstrapRoutes, bootstrapQueryValidator, bootstrapOutputValidator };
+export { bootBootstrapRoutes };

package/server/runtime/bootBootstrapRoutes.test.js

@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import { createContainer } from "../container/index.js";
 import { registerBootstrapPayloadContributor } from "../registries/bootstrapPayloadContributorRegistry.js";
-import { bootBootstrapRoutes, bootstrapQueryValidator } from "./bootBootstrapRoutes.js";
+import { bootBootstrapRoutes } from "./bootBootstrapRoutes.js";
 
 function createReplyDouble() {
   return {
@@ -19,14 +19,6 @@ function createReplyDouble() {
   };
 }
 
-test("bootstrapQueryValidator normalizes generic query payloads", () => {
-  assert.deepEqual(bootstrapQueryValidator.normalize({}), {});
-  assert.deepEqual(bootstrapQueryValidator.normalize({ workspaceSlug: "  AcMe  ", page: "1" }), {
-    workspaceSlug: "  AcMe  ",
-    page: "1"
-  });
-});
-
 test("bootBootstrapRoutes registers GET /api/bootstrap and resolves contributors", async () => {
   const app = createContainer();
   const routes = [];
@@ -56,15 +48,14 @@ test("bootBootstrapRoutes registers GET /api/bootstrap and resolves contributors
 
   const bootstrapRoute = routes.find((entry) => entry.method === "GET" && entry.path === "/api/bootstrap");
   assert.ok(bootstrapRoute);
-  assert.equal(typeof bootstrapRoute.route.queryValidator.normalize, "function");
+  assert.equal(Object.prototype.hasOwnProperty.call(bootstrapRoute.route, "query"), false);
+  assert.equal(Object.prototype.hasOwnProperty.call(bootstrapRoute.route, "responses"), false);
 
   const reply = createReplyDouble();
   await bootstrapRoute.handler(
     {
-      input: {
-        query: {
-          workspaceSlug: "acme"
-        }
+      query: {
+        workspaceSlug: "acme"
       }
     },
     reply

package/server/runtime/fastifyBootstrap.js

@@ -3,6 +3,9 @@ import { normalizeOpaqueId } from "../../shared/support/normalize.js";
 import { isAppError } from "./errors.js";
 import { resolveDefaultSurfaceId } from "../support/appConfig.js";
 
+const JSON_API_CONTENT_TYPE = "application/vnd.api+json";
+const JSON_API_CONTENT_TYPE_PARSER_MARKER = Symbol.for("jskit.fastify.jsonApiContentTypeParserRegistered");
+
 function resolveLoggerLevel({ configuredLevel = "", nodeEnv = "development", allowedLevels = [] } = {}) {
   const normalizedConfiguredLevel = String(configuredLevel || "")
     .trim()
@@ -38,6 +41,48 @@ function createFastifyLoggerOptions({
   };
 }
 
+function createFallbackJsonBodyParser() {
+  return function parseJsonBody(_request, body, done) {
+    const source = typeof body === "string" ? body.trim() : "";
+    if (!source) {
+      done(null, {});
+      return;
+    }
+
+    try {
+      done(null, JSON.parse(source));
+    } catch (error) {
+      if (error && typeof error === "object" && !Array.isArray(error)) {
+        error.statusCode = 400;
+      }
+      done(error);
+    }
+  };
+}
+
+function registerJsonApiContentTypeParser(fastify) {
+  if (!fastify || typeof fastify.addContentTypeParser !== "function") {
+    throw new TypeError("registerJsonApiContentTypeParser requires a Fastify instance.");
+  }
+
+  if (fastify[JSON_API_CONTENT_TYPE_PARSER_MARKER]) {
+    return false;
+  }
+
+  if (typeof fastify.hasContentTypeParser === "function" && fastify.hasContentTypeParser(JSON_API_CONTENT_TYPE)) {
+    fastify[JSON_API_CONTENT_TYPE_PARSER_MARKER] = true;
+    return false;
+  }
+
+  const parser = typeof fastify.getDefaultJsonParser === "function"
+    ? fastify.getDefaultJsonParser("ignore", "ignore")
+    : createFallbackJsonBodyParser();
+
+  fastify.addContentTypeParser(JSON_API_CONTENT_TYPE, { parseAs: "string" }, parser);
+  fastify[JSON_API_CONTENT_TYPE_PARSER_MARKER] = true;
+  return true;
+}
+
 function registerRequestLoggingHooks(
   app,
   {
@@ -124,6 +169,61 @@ function resolveValidationFieldErrors(error) {
   return fieldErrors;
 }
 
+function resolveRequestRouteTransport(request) {
+  const directTransport =
+    request?.routeTransport && typeof request.routeTransport === "object" && !Array.isArray(request.routeTransport)
+      ? request.routeTransport
+      : null;
+  if (directTransport) {
+    return directTransport;
+  }
+
+  const configTransport =
+    request?.routeOptions?.config?.transport &&
+    typeof request.routeOptions.config.transport === "object" &&
+    !Array.isArray(request.routeOptions.config.transport)
+      ? request.routeOptions.config.transport
+      : null;
+  const runtimeTransport =
+    configTransport?.runtime && typeof configTransport.runtime === "object" && !Array.isArray(configTransport.runtime)
+      ? configTransport.runtime
+      : null;
+  if (runtimeTransport) {
+    return runtimeTransport;
+  }
+
+  return configTransport;
+}
+
+function applyRouteTransportErrorResponse(reply, request, error, {
+  statusCode = 500,
+  normalizedErrorCode = ""
+} = {}) {
+  const transport = resolveRequestRouteTransport(request);
+  const errorSerializer = transport && typeof transport.error === "function" ? transport.error : null;
+  if (!errorSerializer) {
+    return false;
+  }
+
+  const payload = errorSerializer(error, {
+    request,
+    reply,
+    statusCode,
+    code: normalizedErrorCode
+  });
+
+  if (payload && typeof payload.then === "function") {
+    throw new TypeError("Route transport error serializer must return synchronously.");
+  }
+
+  if (transport.contentType) {
+    reply.header("Content-Type", transport.contentType);
+  }
+
+  reply.code(statusCode).send(payload);
+  return true;
+}
+
 function registerApiErrorHandler(
   app,
   {
@@ -158,6 +258,12 @@ function registerApiErrorHandler(
     if (Array.isArray(error?.validation)) {
       const fieldErrors = resolveValidationFieldErrors(error);
       const validationErrorCode = normalizedErrorCode || "validation_failed";
+      if (applyRouteTransportErrorResponse(reply, request, error, {
+        statusCode: 400,
+        normalizedErrorCode: validationErrorCode
+      })) {
+        return;
+      }
       reply.code(400).send({
         error: "Validation failed.",
         code: validationErrorCode,
@@ -170,6 +276,12 @@ function registerApiErrorHandler(
     }
 
     if (isAppError(error) || error instanceof ActionRuntimeError) {
+      if (applyRouteTransportErrorResponse(reply, request, error, {
+        statusCode: error.status,
+        normalizedErrorCode: normalizedErrorCode || "app_error"
+      })) {
+        return;
+      }
       if (error.status >= 500) {
         recordDbError(error);
         captureServerError(request, error, error.status);
@@ -222,6 +334,12 @@ function registerApiErrorHandler(
         code: normalizedErrorCode
       };
     }
+    if (applyRouteTransportErrorResponse(reply, request, error, {
+      statusCode,
+      normalizedErrorCode: fallbackErrorCode
+    })) {
+      return;
+    }
     reply.code(statusCode).send(payload);
   });
 }
@@ -364,6 +482,7 @@ async function runGracefulShutdown({
 export {
   resolveLoggerLevel,
   createFastifyLoggerOptions,
+  registerJsonApiContentTypeParser,
   registerRequestLoggingHooks,
   registerApiErrorHandler,
   ensureApiErrorHandling,

package/server/runtime/fastifyBootstrap.test.js

@@ -2,12 +2,13 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import { AppError, isAppError } from "./errors.js";
-import { registerApiErrorHandler, registerRequestLoggingHooks } from "./fastifyBootstrap.js";
+import { registerApiErrorHandler, registerJsonApiContentTypeParser, registerRequestLoggingHooks } from "./fastifyBootstrap.js";
 
 function createFastifyStub() {
   return {
     errorHandler: null,
     hooks: {},
+    contentTypeParsers: new Map(),
     log: {
       error() {}
     },
@@ -16,6 +17,15 @@ function createFastifyStub() {
     },
     addHook(name, handler) {
       this.hooks[name] = handler;
+    },
+    hasContentTypeParser(contentType) {
+      return this.contentTypeParsers.has(String(contentType || "").trim().toLowerCase());
+    },
+    addContentTypeParser(contentType, options, parser) {
+      this.contentTypeParsers.set(String(contentType || "").trim().toLowerCase(), {
+        options,
+        parser
+      });
     }
   };
 }
@@ -157,6 +167,114 @@ test("registerApiErrorHandler keeps known error code for non-app errors", () =>
   });
 });
 
+test("registerApiErrorHandler uses route transport error serializer when present", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+
+  const reply = createReplyStub();
+  const error = new AppError(422, "Validation failed.", {
+    code: "invalid_contact",
+    details: {
+      fieldErrors: {
+        name: "Name is required."
+      }
+    }
+  });
+
+  fastify.errorHandler(
+    error,
+    {
+      routeTransport: {
+        contentType: "application/vnd.api+json",
+        error(currentError, { statusCode, code }) {
+          return {
+            errors: [
+              {
+                status: String(statusCode),
+                code,
+                title: currentError.message
+              }
+            ]
+          };
+        }
+      }
+    },
+    reply
+  );
+
+  assert.equal(reply.statusCode, 422);
+  assert.equal(reply.headers["Content-Type"], "application/vnd.api+json");
+  assert.deepEqual(reply.payload, {
+    errors: [
+      {
+        status: "422",
+        code: "invalid_contact",
+        title: "Validation failed."
+      }
+    ]
+  });
+});
+
+test("registerApiErrorHandler uses route config transport runtime serializer before handler attachment", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+
+  const reply = createReplyStub();
+  const error = new AppError(401, "Authentication required.", {
+    code: "AUTH_POLICY_ERROR"
+  });
+
+  fastify.errorHandler(
+    error,
+    {
+      routeOptions: {
+        config: {
+          transport: {
+            kind: "jsonapi-resource",
+            contentType: "application/vnd.api+json",
+            runtime: {
+              contentType: "application/vnd.api+json",
+              error(currentError, { statusCode, code }) {
+                return {
+                  errors: [
+                    {
+                      status: String(statusCode),
+                      code,
+                      title: currentError.message
+                    }
+                  ]
+                };
+              }
+            }
+          }
+        }
+      }
+    },
+    reply
+  );
+
+  assert.equal(reply.statusCode, 401);
+  assert.equal(reply.headers["Content-Type"], "application/vnd.api+json");
+  assert.deepEqual(reply.payload, {
+    errors: [
+      {
+        status: "401",
+        code: "AUTH_POLICY_ERROR",
+        title: "Authentication required."
+      }
+    ]
+  });
+});
+
+test("registerJsonApiContentTypeParser installs the JSON:API media type parser once", () => {
+  const fastify = createFastifyStub();
+
+  assert.equal(registerJsonApiContentTypeParser(fastify), true);
+  assert.equal(fastify.hasContentTypeParser("application/vnd.api+json"), true);
+  assert.equal(registerJsonApiContentTypeParser(fastify), false);
+  assert.equal(fastify.contentTypeParsers.size, 1);
+});
+
 test("registerRequestLoggingHooks uses configured default surface when getSurface is absent", async () => {
   const fastify = createFastifyStub();
   let loggedPayload = null;

package/server/runtime/moduleConfig.js

@@ -1,6 +1,6 @@
-import { Check, Errors, Parse } from "typebox/value";
 import { deepFreeze } from "../../shared/support/deepFreeze.js";
 import { normalizeObject, normalizeText } from "../../shared/support/normalize.js";
+import { validateSchemaPayload } from "../../shared/validators/schemaPayloadValidation.js";
 
 function normalizeModuleId(value) {
   const moduleId = normalizeText(value);
@@ -17,46 +17,6 @@ function normalizeSchema(value) {
   return value;
 }
 
-function normalizeIssuePath(issue) {
-  const fromInstancePath = normalizeText(issue?.instancePath || issue?.path).replace(/^\//, "").replace(/\//g, ".");
-  if (fromInstancePath) {
-    return fromInstancePath;
-  }
-
-  const missingProperty = normalizeText(issue?.params?.missingProperty);
-  if (missingProperty) {
-    return missingProperty;
-  }
-
-  const additionalProperties = issue?.params?.additionalProperties;
-  if (Array.isArray(additionalProperties) && additionalProperties.length > 0) {
-    const firstAdditional = normalizeText(additionalProperties[0]);
-    if (firstAdditional) {
-      return firstAdditional;
-    }
-  }
-
-  const oneAdditional = normalizeText(additionalProperties);
-  if (oneAdditional) {
-    return oneAdditional;
-  }
-
-  return "(root)";
-}
-
-function normalizeIssueMessage(issue) {
-  const message = normalizeText(issue?.message || issue?.error || issue?.description);
-  return message || "Invalid value.";
-}
-
-function normalizeValidationIssues(rawIssues = []) {
-  return rawIssues.map((issue) => ({
-    path: normalizeIssuePath(issue),
-    message: normalizeIssueMessage(issue),
-    keyword: normalizeText(issue?.keyword)
-  }));
-}
-
 function formatIssues(issues = []) {
   return issues
     .slice(0, 8)
@@ -142,28 +102,38 @@ class ModuleConfigError extends Error {
 }
 
 function validateSchemaOrThrow({ moduleId, schema, value, coerce = false }) {
-  if (coerce) {
-    try {
-      return Parse(schema, value);
-    } catch (cause) {
-      const issues = normalizeValidationIssues([...Errors(schema, value)]);
-      throw new ModuleConfigError(buildInvalidConfigMessage(moduleId, issues), {
-        moduleId,
-        issues,
-        cause
-      });
-    }
-  }
-
-  if (Check(schema, value)) {
-    return value;
+  const schemaDefinition = {
+    schema,
+    mode: "replace"
+  };
+
+  try {
+    return validateSchemaPayload(schemaDefinition, value, {
+      phase: "input",
+      context: `module config "${moduleId}"`
+    });
+  } catch (cause) {
+    const fieldErrors = normalizeObject(cause?.fieldErrors);
+    const issues = Object.keys(fieldErrors).length > 0
+      ? Object.keys(fieldErrors).map((path) => ({
+          path,
+          message: normalizeText(fieldErrors[path], { fallback: "Invalid value." }),
+          keyword: ""
+        }))
+      : [
+          {
+            path: "(root)",
+            message: normalizeText(cause?.message, { fallback: "Invalid value." }),
+            keyword: ""
+          }
+        ];
+
+    throw new ModuleConfigError(buildInvalidConfigMessage(moduleId, issues), {
+      moduleId,
+      issues,
+      cause
+    });
   }
-
-  const issues = normalizeValidationIssues([...Errors(schema, value)]);
-  throw new ModuleConfigError(buildInvalidConfigMessage(moduleId, issues), {
-    moduleId,
-    issues
-  });
 }
 
 function defineModuleConfig({