@jskit-ai/kernel 0.1.54 → 0.1.56

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "type": "module",
   "dependencies": {
-    "typebox": "^1.0.81"
+    "json-rest-schema": "1.x.x"
   },
   "scripts": {
     "test": "node --test"
@@ -40,6 +40,7 @@
     "./shared/support/normalize": "./shared/support/normalize.js",
     "./shared/support/permissions": "./shared/support/permissions.js",
     "./shared/support/crudListFilters": "./shared/support/crudListFilters.js",
+    "./shared/support/crudFieldContract": "./shared/support/crudFieldContract.js",
     "./shared/support/crudLookup": "./shared/support/crudLookup.js",
     "./shared/support/deepFreeze": "./shared/support/deepFreeze.js",
     "./shared/support/listenerSet": "./shared/support/listenerSet.js",

package/server/actions/ActionRuntimeServiceProvider.test.js

@@ -1,9 +1,9 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { createSchema } from "json-rest-schema";
 
 import {
-  EMPTY_INPUT_VALIDATOR,
-  OBJECT_INPUT_VALIDATOR
+  emptyInputValidator
 } from "../../shared/actions/actionContributorHelpers.js";
 import {
   ActionRuntimeServiceProvider,
@@ -109,7 +109,15 @@ test("ActionRuntimeServiceProvider materializes dependencies and surfaces for ap
       dependencies: {
         echoService: "test.echo.service"
       },
-      inputValidator: { schema: OBJECT_INPUT_VALIDATOR },
+      input: {
+        schema: createSchema({
+          value: {
+            type: "string",
+            required: false
+          }
+        }),
+        mode: "patch"
+      },
       idempotency: "none",
       audit: { actionName: "test.echo" },
       observability: {},
@@ -154,7 +162,7 @@ test("ActionRuntimeServiceProvider registers SurfaceRuntime from appConfig when
       kind: "query",
       channels: ["internal"],
       surfacesFrom: "enabled",
-      inputValidator: EMPTY_INPUT_VALIDATOR,
+      input: emptyInputValidator,
       idempotency: "none",
       audit: { actionName: "test.surfaces.from.appconfig" },
       observability: {},
@@ -190,7 +198,7 @@ test("ActionRuntimeServiceProvider materializes custom surfacesFrom aliases regi
       kind: "query",
       channels: ["internal"],
       surfacesFrom: "workspace",
-      inputValidator: EMPTY_INPUT_VALIDATOR,
+      input: emptyInputValidator,
       idempotency: "none",
       audit: { actionName: "test.workspace.alias" },
       observability: {},
@@ -227,7 +235,7 @@ test("ActionRuntimeServiceProvider does not infer service method bindings from a
       dependencies: {
         customerService: "test.customer.service"
       },
-      inputValidator: EMPTY_INPUT_VALIDATOR,
+      input: emptyInputValidator,
       idempotency: "optional",
       audit: { actionName: "test.customer.create" },
       observability: {},
@@ -260,7 +268,7 @@ test("app.actions + resolveActionContributors provide canonical contributor wiri
       kind: "query",
       channels: ["internal"],
       surfaces: ["app"],
-      inputValidator: EMPTY_INPUT_VALIDATOR,
+      input: emptyInputValidator,
       idempotency: "none",
       audit: { actionName: "alpha.one" },
       observability: {},
@@ -277,7 +285,7 @@ test("app.actions + resolveActionContributors provide canonical contributor wiri
       kind: "query",
       channels: ["internal"],
       surfaces: ["app"],
-      inputValidator: EMPTY_INPUT_VALIDATOR,
+      input: emptyInputValidator,
       idempotency: "none",
       audit: { actionName: "beta.one" },
       observability: {},
@@ -320,7 +328,7 @@ test("action runtime execute merges static and per-execution dependencies", asyn
       dependencies: {
         staticService: "test.static.service"
       },
-      inputValidator: EMPTY_INPUT_VALIDATOR,
+      input: emptyInputValidator,
       idempotency: "none",
       audit: { actionName: "test.deps.merge" },
       observability: {},
@@ -364,7 +372,7 @@ test("app.actions accepts custom action domains", () => {
       kind: "query",
       channels: ["internal"],
       surfaces: ["app"],
-      inputValidator: EMPTY_INPUT_VALIDATOR,
+      input: emptyInputValidator,
       idempotency: "none",
       audit: { actionName: "custom.domain.check" },
       observability: {},
@@ -391,7 +399,7 @@ test("app.action registers a single action with default contributor id", () => {
     kind: "query",
     channels: ["internal"],
     surfaces: ["app"],
-    inputValidator: EMPTY_INPUT_VALIDATOR,
+    input: emptyInputValidator,
     idempotency: "none",
     audit: { actionName: "test.single" },
     observability: {},
@@ -415,7 +423,7 @@ test("app.actions requires an array", () => {
   assert.throws(() => app.actions({}), /requires an array/);
 });
 
-test("EMPTY_INPUT_VALIDATOR allows empty input and rejects unexpected fields", async () => {
+test("emptyInputValidator allows empty input and rejects unexpected fields", async () => {
   const app = createSingletonApp();
   const provider = new ActionRuntimeServiceProvider();
   provider.register(app);
@@ -434,7 +442,7 @@ test("EMPTY_INPUT_VALIDATOR allows empty input and rejects unexpected fields", a
       kind: "query",
       channels: ["internal"],
       surfaces: ["app"],
-      inputValidator: EMPTY_INPUT_VALIDATOR,
+      input: emptyInputValidator,
       idempotency: "none",
       audit: { actionName: "test.empty-input" },
       observability: {},
@@ -501,7 +509,7 @@ test("app.actions rejects invalid domain identifiers", () => {
           kind: "query",
           channels: ["internal"],
           surfaces: ["app"],
-          inputValidator: EMPTY_INPUT_VALIDATOR,
+          input: emptyInputValidator,
           idempotency: "none",
           audit: { actionName: "invalid.domain" },
           observability: {},
@@ -533,7 +541,7 @@ test("app.actions rejects unsupported surfacesFrom aliases", () => {
       kind: "query",
       channels: ["internal"],
       surfacesFrom: "workspace",
-      inputValidator: EMPTY_INPUT_VALIDATOR,
+      input: emptyInputValidator,
       idempotency: "none",
       audit: { actionName: "workspace.alias.invalid" },
       observability: {},

package/server/http/lib/kernel.test.js

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { createSchema } from "json-rest-schema";
 import { registerActionContextContributor } from "../../actions/ActionRuntimeServiceProvider.js";
 import { createApplication } from "../../kernel/index.js";
 import { createRouter } from "./router.js";
@@ -12,12 +13,22 @@ function createFastifyStub() {
     routes,
     setErrorHandlerCalls: 0,
     errorHandler: null,
+    contentTypeParsers: new Map(),
     route(definition) {
       routes.push(definition);
     },
     setErrorHandler(handler) {
       this.errorHandler = handler;
       this.setErrorHandlerCalls += 1;
+    },
+    hasContentTypeParser(contentType) {
+      return this.contentTypeParsers.has(String(contentType || "").trim().toLowerCase());
+    },
+    addContentTypeParser(contentType, options, parser) {
+      this.contentTypeParsers.set(String(contentType || "").trim().toLowerCase(), {
+        options,
+        parser
+      });
     }
   };
 }
@@ -508,6 +519,38 @@ test("registerHttpRuntime installs API error handling once by default", () => {
 
   assert.equal(fastify.setErrorHandlerCalls, 1);
   assert.equal(typeof fastify.errorHandler, "function");
+  assert.equal(fastify.contentTypeParsers.size, 0);
+});
+
+test("registerHttpRuntime installs the JSON:API parser only when a registered route accepts JSON:API request bodies", () => {
+  const app = createApplication();
+  const fastify = createFastifyStub();
+  const router = createRouter();
+
+  router.post(
+    "/jsonapi-body",
+    {
+      body: {
+        schema: createSchema({})
+      },
+      transport: {
+        kind: "jsonapi-resource",
+        contentType: "application/vnd.api+json"
+      }
+    },
+    async (_request, reply) => {
+      reply.code(204).send();
+    }
+  );
+
+  app.instance("jskit.fastify", fastify);
+  app.instance("jskit.http.router", router);
+
+  registerHttpRuntime(app);
+  registerHttpRuntime(app);
+
+  assert.equal(fastify.contentTypeParsers.has("application/vnd.api+json"), true);
+  assert.equal(fastify.contentTypeParsers.size, 1);
 });
 
 test("registerHttpRuntime can disable automatic API error handling", () => {
@@ -717,6 +760,109 @@ test("registerRoutes attaches request.input when route input transforms are conf
   assert.equal(reply.statusCode, 200);
 });
 
+test("registerRoutes applies transport request transforms before route input normalization", async () => {
+  const fastify = createFastifyStub();
+
+  registerRoutes(fastify, {
+    routes: [
+      {
+        method: "POST",
+        path: "/transport-input",
+        transport: {
+          kind: "jsonapi-resource",
+          request: {
+            body(body) {
+              return body?.data?.attributes || {};
+            }
+          }
+        },
+        input: {
+          body: (body) => ({
+            name: String(body?.name || "").trim()
+          })
+        },
+        handler: async (request, reply) => {
+          assert.equal(request.routeOptions.config.transport.kind, "jsonapi-resource");
+          assert.deepEqual(request.input, {
+            body: {
+              name: "Alice"
+            },
+            query: undefined,
+            params: undefined
+          });
+          reply.code(200).send({ ok: true });
+        }
+      }
+    ]
+  });
+
+  const request = {
+    body: {
+      data: {
+        type: "contacts",
+        attributes: {
+          name: "  Alice  "
+        }
+      }
+    }
+  };
+  const reply = createReplyStub();
+
+  await fastify.routes[0].handler(request, reply);
+
+  assert.equal(reply.statusCode, 200);
+});
+
+test("registerRoutes does not invoke transport body transforms for bodyless requests", async () => {
+  const fastify = createFastifyStub();
+  let bodyTransformCalls = 0;
+
+  registerRoutes(fastify, {
+    routes: [
+      {
+        method: "GET",
+        path: "/transport-input-no-body",
+        transport: {
+          kind: "jsonapi-resource",
+          request: {
+            body() {
+              bodyTransformCalls += 1;
+              throw new Error("transport body transform should not run");
+            }
+          }
+        },
+        input: {
+          query: (query) => ({
+            page: Number(query?.page || 1)
+          })
+        },
+        handler: async (request, reply) => {
+          assert.deepEqual(request.input, {
+            body: undefined,
+            query: {
+              page: 2
+            },
+            params: undefined
+          });
+          reply.code(200).send({ ok: true });
+        }
+      }
+    ]
+  });
+
+  const request = {
+    query: {
+      page: "2"
+    }
+  };
+  const reply = createReplyStub();
+
+  await fastify.routes[0].handler(request, reply);
+
+  assert.equal(reply.statusCode, 200);
+  assert.equal(bodyTransformCalls, 0);
+});
+
 test("registerRoutes leaves request.input undefined when route input is not configured", async () => {
   const fastify = createFastifyStub();
 
@@ -740,6 +886,214 @@ test("registerRoutes leaves request.input undefined when route input is not conf
   assert.equal(reply.statusCode, 200);
 });
 
+test("registerRoutes applies output transform on reply.send without changing handler shape", async () => {
+  const fastify = createFastifyStub();
+
+  registerRoutes(fastify, {
+    routes: [
+      {
+        method: "GET",
+        path: "/transport-output",
+        transport: {
+          kind: "jsonapi-resource"
+        },
+        output(payload) {
+          return {
+            data: payload
+          };
+        },
+        handler: async (request, reply) => {
+          assert.equal(request.routeOptions.config.transport.kind, "jsonapi-resource");
+          reply.code(200).send({
+            id: "7",
+            name: "Alice"
+          });
+        }
+      }
+    ]
+  });
+
+  const request = {};
+  const reply = createReplyStub();
+
+  await fastify.routes[0].handler(request, reply);
+
+  assert.equal(reply.statusCode, 200);
+  assert.equal(reply.headers["Content-Type"], undefined);
+  assert.deepEqual(reply.payload, {
+    data: {
+      id: "7",
+      name: "Alice"
+    }
+  });
+});
+
+test("registerRoutes applies transport response transforms before reply serialization", async () => {
+  const fastify = createFastifyStub();
+
+  registerRoutes(fastify, {
+    routes: [
+      {
+        method: "GET",
+        path: "/transport-response",
+        transport: {
+          kind: "jsonapi-resource",
+          contentType: "application/vnd.api+json",
+          response(payload) {
+            return {
+              data: {
+                type: "contacts",
+                id: String(payload?.id || ""),
+                attributes: {
+                  name: String(payload?.name || "")
+                }
+              }
+            };
+          }
+        },
+        handler: async (_request, reply) => {
+          reply.code(200).send({
+            id: 7,
+            name: "Alice"
+          });
+        }
+      }
+    ]
+  });
+
+  const request = {};
+  const reply = createReplyStub();
+
+  await fastify.routes[0].handler(request, reply);
+
+  assert.equal(reply.statusCode, 200);
+  assert.equal(reply.headers["Content-Type"], "application/vnd.api+json");
+  assert.deepEqual(reply.payload, {
+    data: {
+      type: "contacts",
+      id: "7",
+      attributes: {
+        name: "Alice"
+      }
+    }
+  });
+});
+
+test("registerRoutes exposes full transport runtime on Fastify route config for pre-handler error serialization", () => {
+  const fastify = createFastifyStub();
+  const transport = {
+    kind: "jsonapi-resource",
+    contentType: "application/vnd.api+json",
+    error() {
+      return {
+        errors: []
+      };
+    }
+  };
+
+  registerRoutes(fastify, {
+    routes: [
+      {
+        method: "GET",
+        path: "/transport-runtime",
+        transport,
+        handler: async (_request, reply) => {
+          reply.code(200).send({ ok: true });
+        }
+      }
+    ]
+  });
+
+  assert.equal(fastify.routes[0].config.transport.kind, "jsonapi-resource");
+  assert.equal(fastify.routes[0].config.transport.contentType, "application/vnd.api+json");
+  assert.deepEqual(fastify.routes[0].config.transport.runtime, transport);
+});
+
+test("registerRoutes keeps transport response payload when output transform returns undefined", async () => {
+  const fastify = createFastifyStub();
+
+  registerRoutes(fastify, {
+    routes: [
+      {
+        method: "GET",
+        path: "/transport-response-output-undefined",
+        transport: {
+          kind: "jsonapi-resource",
+          contentType: "application/vnd.api+json",
+          response(payload) {
+            return {
+              data: {
+                type: "contacts",
+                id: String(payload?.id || ""),
+                attributes: {
+                  name: String(payload?.name || "")
+                }
+              }
+            };
+          }
+        },
+        output() {
+          return undefined;
+        },
+        handler: async (_request, reply) => {
+          reply.code(200).send({
+            id: 7,
+            name: "Alice"
+          });
+        }
+      }
+    ]
+  });
+
+  const request = {};
+  const reply = createReplyStub();
+
+  await fastify.routes[0].handler(request, reply);
+
+  assert.equal(reply.statusCode, 200);
+  assert.equal(reply.headers["Content-Type"], "application/vnd.api+json");
+  assert.deepEqual(reply.payload, {
+    data: {
+      type: "contacts",
+      id: "7",
+      attributes: {
+        name: "Alice"
+      }
+    }
+  });
+});
+
+test("registerRoutes sets transport content type on successful replies", async () => {
+  const fastify = createFastifyStub();
+
+  registerRoutes(fastify, {
+    routes: [
+      {
+        method: "GET",
+        path: "/transport-content-type",
+        transport: {
+          kind: "jsonapi-resource",
+          contentType: "application/vnd.api+json"
+        },
+        handler: async (_request, reply) => {
+          reply.code(200).send({
+            data: {
+              type: "contacts",
+              id: "7"
+            }
+          });
+        }
+      }
+    ]
+  });
+
+  const reply = createReplyStub();
+  await fastify.routes[0].handler({}, reply);
+
+  assert.equal(reply.statusCode, 200);
+  assert.equal(reply.headers["Content-Type"], "application/vnd.api+json");
+});
+
 test("registerRoutes rejects invalid route input transform definitions", () => {
   const fastify = createFastifyStub();
 
@@ -761,6 +1115,99 @@ test("registerRoutes rejects invalid route input transform definitions", () => {
   );
 });
 
+test("registerRoutes rejects invalid transport definitions", () => {
+  const fastify = createFastifyStub();
+
+  assert.throws(
+    () =>
+      registerRoutes(fastify, {
+        routes: [
+          {
+            method: "GET",
+            path: "/invalid-transport",
+            transport: {
+              kind: "weird"
+            },
+            handler: async () => {}
+          }
+        ]
+      }),
+    /transport\.kind must be one of: command, jsonapi-resource/
+  );
+});
+
+test("registerRoutes enforces request content type for unsafe transport routes", async () => {
+  const fastify = createFastifyStub();
+
+  registerRoutes(fastify, {
+    routes: [
+      {
+        method: "POST",
+        path: "/transport-content-type-enforced",
+        body: {
+          type: "object",
+          additionalProperties: true
+        },
+        transport: {
+          kind: "jsonapi-resource",
+          contentType: "application/vnd.api+json"
+        },
+        handler: async (_request, reply) => {
+          reply.code(200).send({ ok: true });
+        }
+      }
+    ]
+  });
+
+  await assert.rejects(
+    () =>
+      fastify.routes[0].handler(
+        {
+          headers: {
+            "content-type": "application/json"
+          }
+        },
+        createReplyStub()
+      ),
+    (error) => {
+      assert.equal(error?.status, 415);
+      assert.equal(error?.code, "unsupported_media_type");
+      return true;
+    }
+  );
+});
+
+test("registerRoutes does not enforce request content type for bodyless unsafe transport routes", async () => {
+  const fastify = createFastifyStub();
+
+  registerRoutes(fastify, {
+    routes: [
+      {
+        method: "POST",
+        path: "/transport-content-type-bodyless",
+        transport: {
+          kind: "jsonapi-resource",
+          contentType: "application/vnd.api+json"
+        },
+        handler: async (_request, reply) => {
+          reply.code(204).send();
+        }
+      }
+    ]
+  });
+
+  const reply = createReplyStub();
+  await fastify.routes[0].handler(
+    {
+      headers: {}
+    },
+    reply
+  );
+
+  assert.equal(reply.statusCode, 204);
+  assert.equal(reply.payload, undefined);
+});
+
 test("registerRoutes resolves middleware aliases and groups", async () => {
   const fastify = createFastifyStub();
   const observed = {