@jskit-ai/kernel 0.1.185 → 0.1.186

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.185",
+  "version": "0.1.186",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "^1.0.17"

package/server/runtime/fastifyBootstrap.js

@@ -1,5 +1,5 @@
 import { ActionRuntimeError } from "../../shared/actions/actionDefinitions.js";
-import { normalizeOpaqueId } from "../../shared/support/normalize.js";
+import { normalizeOpaqueId, normalizeTransactionOutcome } from "../../shared/support/normalize.js";
 import { resolveDefaultSurfaceId } from "../support/appConfig.js";
 
 const JSON_API_CONTENT_TYPE = "application/vnd.api+json";
@@ -255,7 +255,9 @@ function resolveRequestRouteTransport(request) {
 
 function applyRouteTransportErrorResponse(reply, request, error, {
   statusCode = 500,
-  normalizedErrorCode = ""
+  normalizedErrorCode = "",
+  message = error?.message,
+  exposeDetails = true
 } = {}) {
   const transport = resolveRequestRouteTransport(request);
   const errorSerializer = transport && typeof transport.error === "function" ? transport.error : null;
@@ -267,7 +269,9 @@ function applyRouteTransportErrorResponse(reply, request, error, {
     request,
     reply,
     statusCode,
-    code: normalizedErrorCode
+    code: normalizedErrorCode,
+    message,
+    exposeDetails
   });
 
   if (payload && typeof payload.then === "function") {
@@ -282,6 +286,36 @@ function applyRouteTransportErrorResponse(reply, request, error, {
   return true;
 }
 
+function resolveApiErrorStatus(error, code) {
+  // JSON REST's public error codes need HTTP classification even without status hints.
+  switch (code) {
+    case "REST_API_VALIDATION":
+      return 422;
+    case "REST_API_RESOURCE":
+      switch (error?.subtype) {
+        case "not_found": return 404;
+        case "forbidden": return 403;
+        case "conflict": return 409;
+        default: return 400;
+      }
+    case "REST_API_VERSION_CONFLICT":
+      return 409;
+    case "REST_API_PRECONDITION_FAILED":
+      return 412;
+    case "REST_API_FIELDSET_INVALID":
+    case "REST_API_INCLUDE_INVALID":
+      return 400;
+    case "REST_API_PAYLOAD":
+      return error?.statusCode === 413 ? 413 : 400;
+    case "REST_API_TEMPORAL_DATA_INVALID":
+      return 500;
+    default: {
+      const status = Number(error?.statusCode || error?.status);
+      return Number.isInteger(status) && status >= 400 && status <= 599 ? status : 500;
+    }
+  }
+}
+
 function registerApiErrorHandler(
   app,
   {
@@ -308,10 +342,10 @@ function registerApiErrorHandler(
 
   app.setErrorHandler((error, request, reply) => {
     const normalizedErrorCode = String(error?.code || "").trim();
+    const transactionOutcome = normalizeTransactionOutcome(error?.transactionOutcome);
+    const outcomeFields = transactionOutcome ? { transactionOutcome } : {};
     const isCsrfErrorCode = normalizedErrorCode.startsWith("FST_CSRF_");
-    const statusFromError = Number(error?.statusCode || error?.status);
-    const statusCode =
-      Number.isInteger(statusFromError) && statusFromError >= 400 && statusFromError <= 599 ? statusFromError : 500;
+    const statusCode = resolveApiErrorStatus(error, normalizedErrorCode);
 
     if (Array.isArray(error?.validation)) {
       const fieldErrors = resolveValidationFieldErrors(error);
@@ -325,6 +359,7 @@ function registerApiErrorHandler(
       reply.code(400).send({
         error: "Validation failed.",
         code: validationErrorCode,
+        ...outcomeFields,
         fieldErrors,
         details: {
           fieldErrors
@@ -336,7 +371,8 @@ function registerApiErrorHandler(
     if (isAppError(error) || error instanceof ActionRuntimeError) {
       if (applyRouteTransportErrorResponse(reply, request, error, {
         statusCode: error.status,
-        normalizedErrorCode: normalizedErrorCode || "app_error"
+        normalizedErrorCode: normalizedErrorCode || "app_error",
+        exposeDetails: shouldExposeAppErrorDetails(normalizedErrorCode)
       })) {
         return;
       }
@@ -349,7 +385,8 @@ function registerApiErrorHandler(
       const appErrorCode = normalizedErrorCode || "app_error";
       const payload = {
         error: error.message,
-        code: appErrorCode
+        code: appErrorCode,
+        ...outcomeFields
       };
       if (error.details && shouldExposeAppErrorDetails(appErrorCode)) {
         payload.details = error.details;
@@ -385,7 +422,8 @@ function registerApiErrorHandler(
       normalizedErrorCode || (statusCode >= 500 ? "internal_server_error" : "request_failed");
     const payload = {
       error: message,
-      code: fallbackErrorCode
+      code: fallbackErrorCode,
+      ...outcomeFields
     };
     if (isCsrfErrorCode) {
       payload.details = {
@@ -394,7 +432,9 @@ function registerApiErrorHandler(
     }
     if (applyRouteTransportErrorResponse(reply, request, error, {
       statusCode,
-      normalizedErrorCode: fallbackErrorCode
+      normalizedErrorCode: fallbackErrorCode,
+      message,
+      exposeDetails: statusCode < 500
     })) {
       return;
     }

package/server/runtime/fastifyBootstrap.test.js

@@ -155,6 +155,44 @@ test("registerApiErrorHandler includes internal_server_error code for unhandled
   assert.equal(reply.payload.error, "Internal server error.");
 });
 
+test("registerApiErrorHandler exposes only allowlisted transaction outcomes", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+  for (const transactionOutcome of ["none", "pending", "committed", "rolledBack", "unknown"]) {
+    const error = Object.assign(new Error("Private SQL failure"), {
+      transactionOutcome,
+      cause: { password: "private" },
+      cleanupErrors: [{ message: "private cleanup" }]
+    });
+    const reply = createReplyStub();
+    fastify.errorHandler(error, {}, reply);
+    assert.equal(reply.statusCode, 500);
+    assert.deepEqual(reply.payload, {
+      error: "Internal server error.",
+      code: "internal_server_error",
+      transactionOutcome
+    });
+  }
+  for (const transactionOutcome of [undefined, "success", { secret: "private" }]) {
+    const reply = createReplyStub();
+    fastify.errorHandler(Object.assign(new Error("private"), { transactionOutcome }), {}, reply);
+    assert.equal(Object.hasOwn(reply.payload, "transactionOutcome"), false);
+  }
+});
+
+test("AppError and validation payloads retain transaction outcomes", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+  for (const error of [
+    Object.assign(new AppError(409, "Conflict."), { transactionOutcome: "rolledBack" }),
+    { validation: [{ instancePath: "/title", message: "Required" }], transactionOutcome: "none" }
+  ]) {
+    const reply = createReplyStub();
+    fastify.errorHandler(error, {}, reply);
+    assert.equal(reply.payload.transactionOutcome, error.transactionOutcome);
+  }
+});
+
 test("registerApiErrorHandler keeps known error code for non-app errors", () => {
   const fastify = createFastifyStub();
   registerApiErrorHandler(fastify, { isAppError });

package/shared/support/normalize.js

@@ -1,3 +1,9 @@
+const TRANSACTION_OUTCOMES = Object.freeze(["none", "pending", "committed", "rolledBack", "unknown"]);
+
+function normalizeTransactionOutcome(value) {
+  return TRANSACTION_OUTCOMES.includes(value) ? value : "";
+}
+
 function normalizeText(value, { fallback = "" } = {}) {
   const normalized = String(value || "").trim();
   return normalized || fallback;
@@ -351,6 +357,8 @@ function ensureNonEmptyText(value, label = "value") {
 }
 
 export {
+  TRANSACTION_OUTCOMES,
+  normalizeTransactionOutcome,
   normalizeText,
   hasValue,
   normalizeBoolean,

package/shared/support/normalize.test.js

@@ -17,9 +17,19 @@ import {
   normalizeOneOf,
   normalizeQueryToken,
   normalizeText,
+  normalizeTransactionOutcome,
   normalizeUniqueTextList
 } from "./normalize.js";
 
+test("normalizeTransactionOutcome accepts only the documented literal outcomes", () => {
+  for (const value of ["none", "pending", "committed", "rolledBack", "unknown"]) {
+    assert.equal(normalizeTransactionOutcome(value), value);
+  }
+  for (const value of [undefined, null, false, 0, "", "rolledback", " committed ", { toString: () => "committed" }]) {
+    assert.equal(normalizeTransactionOutcome(value), "");
+  }
+});
+
 test("hasValue returns false for nullish and blank text, true otherwise", () => {
   assert.equal(hasValue(null), false);
   assert.equal(hasValue(undefined), false);