@jskit-ai/kernel 0.1.22 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "type": "module",
   "dependencies": {
     "typebox": "^1.0.81"

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

@@ -96,17 +96,26 @@ test("registerRoutes attaches request.executeAction and applies action context c
 
   registerActionContextContributor(app, "test.auth.actionContextContributor", () => ({
     contributorId: "test.auth",
-    contribute({ request }) {
+    contribute({ request, definition }) {
       return {
         actor: request?.user || null,
         permissions: Array.isArray(request?.permissions) ? request.permissions.slice() : [],
         workspace: request?.workspace || null,
-        membership: request?.membership || null
+        membership: request?.membership || null,
+        requestMeta: {
+          definitionId: definition?.id || ""
+        }
       };
     }
   }));
 
   app.instance("actionExecutor", {
+    getDefinition(actionId) {
+      return {
+        id: actionId,
+        surfaces: ["coffie"]
+      };
+    },
     async execute(payload) {
       observed.push(payload);
       return {
@@ -134,7 +143,7 @@ test("registerRoutes attaches request.executeAction and applies action context c
               slug: "main"
             };
             request.membership = {
-              roleId: "owner"
+              roleSid: "owner"
             };
           }
         ],
@@ -191,10 +200,11 @@ test("registerRoutes attaches request.executeAction and applies action context c
   assert.equal(observed[0].context.actor?.id, 7);
   assert.deepEqual(observed[0].context.permissions, ["settings.read"]);
   assert.equal(observed[0].context.workspace?.id, 10);
-  assert.equal(observed[0].context.membership?.roleId, "owner");
+  assert.equal(observed[0].context.membership?.roleSid, "owner");
   assert.equal(observed[0].context.surface, "coffie");
   assert.equal(observed[0].context.channel, "api");
   assert.equal(observed[0].context.requestMeta.commandId, "cmd-1");
+  assert.equal(observed[0].context.requestMeta.definitionId, "settings.read");
   assert.equal(observed[0].context.requestMeta.request, request);
 
   assert.equal(observed[1].actionId, "settings.override");

package/server/http/lib/requestActionExecutor.js

@@ -83,6 +83,7 @@ async function enrichActionExecutionContext({
   request = null,
   actionId = "",
   version = null,
+  definition = null,
   input = {},
   deps = {},
   channel = "api",
@@ -108,6 +109,7 @@ async function enrichActionExecutionContext({
       request,
       actionId: normalizedActionId,
       version: version == null ? null : version,
+      definition,
       input: normalizedInput,
       deps: normalizedDeps,
       channel: normalizedChannel,
@@ -201,6 +203,10 @@ function attachRequestActionExecutor({
     if (!actionExecutor || typeof actionExecutor.execute !== "function") {
       throw new RouteRegistrationError(`"${normalizedActionExecutorToken}" must provide execute().`);
     }
+    const definition =
+      typeof actionExecutor.getDefinition === "function"
+        ? actionExecutor.getDefinition(source.actionId, source.version == null ? null : source.version)
+        : null;
 
     const baseContext = buildActionExecutionContext({
       request,
@@ -213,6 +219,7 @@ function attachRequestActionExecutor({
       request,
       actionId: source.actionId,
       version: source.version == null ? null : source.version,
+      definition,
       input: normalizedInput,
       deps: normalizedDeps,
       channel: normalizedChannel,

package/server/runtime/fastifyBootstrap.js

@@ -144,6 +144,10 @@ function registerApiErrorHandler(
   const recordDbError = typeof onRecordDbError === "function" ? onRecordDbError : () => {};
   const captureServerError = typeof onCaptureServerError === "function" ? onCaptureServerError : () => {};
 
+  function shouldExposeAppErrorDetails(errorCode = "") {
+    return String(errorCode || "").trim() !== "ACTION_PERMISSION_DENIED";
+  }
+
   app.setErrorHandler((error, request, reply) => {
     const normalizedErrorCode = String(error?.code || "").trim();
     const isCsrfErrorCode = normalizedErrorCode.startsWith("FST_CSRF_");
@@ -177,7 +181,7 @@ function registerApiErrorHandler(
         error: error.message,
         code: appErrorCode
       };
-      if (error.details) {
+      if (error.details && shouldExposeAppErrorDetails(appErrorCode)) {
         payload.details = error.details;
         if (error.details.fieldErrors) {
           payload.fieldErrors = error.details.fieldErrors;

package/server/runtime/fastifyBootstrap.test.js

@@ -103,6 +103,28 @@ test("registerApiErrorHandler falls back to app_error code for AppError without
   assert.equal(reply.payload.code, "app_error");
 });
 
+test("registerApiErrorHandler hides internal permission details for action permission denials", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+
+  const reply = createReplyStub();
+  const error = new AppError(403, "Forbidden.", {
+    code: "ACTION_PERMISSION_DENIED",
+    details: {
+      actionId: "crud.breeds.list",
+      permission: "crud.breeds.list"
+    }
+  });
+
+  fastify.errorHandler(error, {}, reply);
+
+  assert.equal(reply.statusCode, 403);
+  assert.deepEqual(reply.payload, {
+    error: "Forbidden.",
+    code: "ACTION_PERMISSION_DENIED"
+  });
+});
+
 test("registerApiErrorHandler includes internal_server_error code for unhandled 500 errors", () => {
   const fastify = createFastifyStub();
   registerApiErrorHandler(fastify, { isAppError });

package/server/runtime/serviceAuthorization.test.js

@@ -88,12 +88,12 @@ test("requireAuth allows namespace wildcard permissions", () => {
       {
         context: {
           actor: { id: 1 },
-          permissions: ["crud_contacts.*"]
+          permissions: ["crud.contacts.*"]
         }
       },
       {
         require: "all",
-        permissions: ["crud_contacts.update"]
+        permissions: ["crud.contacts.update"]
       }
     )
   );

package/server/support/shellOutlets.js

@@ -12,6 +12,125 @@ import {
 
 const VUE_DISCOVERY_IGNORED_ERROR_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM"]);
 const LOCK_FILE_RELATIVE_PATH = ".jskit/lock.json";
+const ROUTE_TAG_PATTERN = /<route\b([^>]*)>([\s\S]*?)<\/route>/g;
+const ATTRIBUTE_PATTERN = /([:@]?[A-Za-z_][A-Za-z0-9_-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
+
+function parseTagAttributes(attributesSource = "") {
+  const attributes = {};
+  const source = String(attributesSource || "");
+  for (const match of source.matchAll(ATTRIBUTE_PATTERN)) {
+    const attributeName = normalizeText(match[1]);
+    if (!attributeName) {
+      continue;
+    }
+
+    const hasValue = match[2] != null || match[3] != null;
+    const attributeValue = hasValue ? String(match[2] ?? match[3] ?? "") : true;
+    attributes[attributeName] = attributeValue;
+  }
+
+  return attributes;
+}
+
+function isDefaultEnabled(value) {
+  if (value === true) {
+    return true;
+  }
+  if (value === false || value == null) {
+    return false;
+  }
+
+  const normalized = normalizeText(value).toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+
+function normalizeAppRouteOutletTarget({
+  outlet = {},
+  sourcePath = ""
+} = {}) {
+  const outletRecord = normalizeObject(outlet);
+  const outletTargetId = normalizeShellOutletTargetId(
+    `${normalizeText(outletRecord.host)}:${normalizeText(outletRecord.position)}`
+  );
+  if (!outletTargetId) {
+    return null;
+  }
+
+  const separatorIndex = outletTargetId.indexOf(":");
+  const host = outletTargetId.slice(0, separatorIndex);
+  const position = outletTargetId.slice(separatorIndex + 1);
+  return Object.freeze({
+    id: outletTargetId,
+    host,
+    position,
+    default: isDefaultEnabled(outletRecord.default),
+    sourcePath
+  });
+}
+
+function discoverRouteMetaOutletTargetsFromVueSource(source = "", { context = "shell layout" } = {}) {
+  const sourceText = String(source || "");
+  const resolvedContext = normalizeText(context) || "shell layout";
+  const targetById = new Map();
+  let defaultTargetId = "";
+
+  for (const routeTagMatch of sourceText.matchAll(ROUTE_TAG_PATTERN)) {
+    const routeTagAttributes = parseTagAttributes(routeTagMatch[1]);
+    const routeTagLanguage = normalizeText(routeTagAttributes.lang).toLowerCase();
+    if (routeTagLanguage !== "json") {
+      continue;
+    }
+
+    const routeMetaSource = String(routeTagMatch[2] || "").trim();
+    if (!routeMetaSource) {
+      continue;
+    }
+
+    let routeMetaRecord = null;
+    try {
+      routeMetaRecord = JSON.parse(routeMetaSource);
+    } catch (error) {
+      throw new Error(
+        `${resolvedContext} contains invalid <route lang="json"> block: ${String(error?.message || error || "unknown error")}`
+      );
+    }
+
+    const routeMeta = normalizeObject(normalizeObject(routeMetaRecord).meta);
+    const jskitMeta = normalizeObject(routeMeta.jskit);
+    const placementsMeta = normalizeObject(jskitMeta.placements);
+    const outlets = Array.isArray(placementsMeta.outlets) ? placementsMeta.outlets : [];
+    for (const outlet of outlets) {
+      const normalizedTarget = normalizeAppRouteOutletTarget({
+        outlet,
+        sourcePath: resolvedContext
+      });
+      if (!normalizedTarget) {
+        continue;
+      }
+      if (targetById.has(normalizedTarget.id)) {
+        throw new Error(`${resolvedContext} contains duplicate route meta placement target "${normalizedTarget.id}".`);
+      }
+      if (normalizedTarget.default === true) {
+        if (defaultTargetId && defaultTargetId !== normalizedTarget.id) {
+          throw new Error(
+            `${resolvedContext} defines multiple default route meta placement targets: "${defaultTargetId}" and "${normalizedTarget.id}".`
+          );
+        }
+        defaultTargetId = normalizedTarget.id;
+      }
+      targetById.set(normalizedTarget.id, normalizedTarget);
+    }
+  }
+
+  return Object.freeze({
+    targets: Object.freeze([...targetById.values()]),
+    defaultTargetId
+  });
+}
 
 async function collectVueFilePaths(rootDirectoryPath) {
   const absoluteRoot = path.resolve(String(rootDirectoryPath || ""));
@@ -154,15 +273,27 @@ async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" }
   for (const absoluteFilePath of vueFiles) {
     const relativePath = toPosixPath(path.relative(resolvedAppRoot, absoluteFilePath));
     const source = await readFile(absoluteFilePath, "utf8");
-    if (!source.includes("<ShellOutlet")) {
+    if (!source.includes("<ShellOutlet") && !source.includes("<route")) {
       continue;
     }
 
-    const discovered = discoverShellOutletTargetsFromVueSource(source, {
-      context: relativePath
-    });
-    const targets = Array.isArray(discovered.targets) ? discovered.targets : [];
-    for (const target of targets) {
+    const discoveredShellOutlets = source.includes("<ShellOutlet")
+      ? discoverShellOutletTargetsFromVueSource(source, {
+          context: relativePath
+        })
+      : { targets: [], defaultTargetId: "" };
+    const discoveredRouteMetaOutlets = source.includes("<route")
+      ? discoverRouteMetaOutletTargetsFromVueSource(source, {
+          context: relativePath
+        })
+      : { targets: [], defaultTargetId: "" };
+    const discoveredTargets = [
+      ...(Array.isArray(discoveredShellOutlets.targets) ? discoveredShellOutlets.targets : []),
+      ...(Array.isArray(discoveredRouteMetaOutlets.targets)
+        ? discoveredRouteMetaOutlets.targets
+        : [])
+    ];
+    for (const target of discoveredTargets) {
       if (!targetById.has(target.id)) {
         targetById.set(
           target.id,
@@ -174,20 +305,21 @@ async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" }
       }
     }
 
-    const discoveredDefaultTargetId = normalizeShellOutletTargetId(discovered.defaultTargetId);
-    if (!discoveredDefaultTargetId) {
-      continue;
-    }
+    const discoveredDefaultTargetIds = [
+      normalizeShellOutletTargetId(discoveredShellOutlets.defaultTargetId),
+      normalizeShellOutletTargetId(discoveredRouteMetaOutlets.defaultTargetId)
+    ].filter(Boolean);
+    for (const discoveredDefaultTargetId of discoveredDefaultTargetIds) {
+      if (defaultTargetId && discoveredDefaultTargetId !== defaultTargetId) {
+        throw new Error(
+          `Multiple default ShellOutlet targets found in app source: "${defaultTargetId}" (${defaultTargetSource}) and ` +
+          `"${discoveredDefaultTargetId}" (${relativePath}).`
+        );
+      }
 
-    if (defaultTargetId && discoveredDefaultTargetId !== defaultTargetId) {
-      throw new Error(
-        `Multiple default ShellOutlet targets found in app source: "${defaultTargetId}" (${defaultTargetSource}) and ` +
-        `"${discoveredDefaultTargetId}" (${relativePath}).`
-      );
+      defaultTargetId = discoveredDefaultTargetId;
+      defaultTargetSource = relativePath;
     }
-
-    defaultTargetId = discoveredDefaultTargetId;
-    defaultTargetSource = relativePath;
   }
 
   const packageTargets = await collectInstalledPackageOutletTargets(resolvedAppRoot);

package/server/support/shellOutlets.test.js

@@ -174,6 +174,52 @@ test("discoverShellOutletTargetsFromApp returns targets with sourcePath and defa
   });
 });
 
+test("discoverShellOutletTargetsFromApp discovers route meta placement outlets", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFileInApp(
+      appRoot,
+      "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/contact-tools.vue",
+      `<template><section /></template>
+
+<route lang="json">
+{
+  "meta": {
+    "jskit": {
+      "placements": {
+        "outlets": [
+          {
+            "host": "contact-tools",
+            "position": "sub-pages"
+          }
+        ]
+      }
+    }
+  }
+}
+</route>
+`
+    );
+
+    const discovered = await discoverShellOutletTargetsFromApp({ appRoot });
+    assert.deepEqual(discovered.targets, [
+      {
+        id: "contact-tools:sub-pages",
+        host: "contact-tools",
+        position: "sub-pages",
+        default: false,
+        sourcePath: "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/contact-tools.vue"
+      }
+    ]);
+
+    const target = await resolveShellOutletPlacementTargetFromApp({
+      appRoot,
+      placement: "contact-tools:sub-pages",
+      context: "ui-generator"
+    });
+    assert.equal(target.id, "contact-tools:sub-pages");
+  });
+});
+
 test("resolveShellOutletPlacementTargetFromApp supports explicit placement override", async () => {
   await withTempApp(async (appRoot) => {
     await writeFileInApp(

package/shared/actions/executionContext.test.js

@@ -42,11 +42,11 @@ test("normalizeExecutionContext keeps actor payload generic", () => {
     actor: {
       id: "user_1",
       email: "UPPER@EXAMPLE.COM",
-      roleId: "OWNER",
+      roleSid: "OWNER",
       customFlag: true
     },
     membership: {
-      roleId: "OWNER",
+      roleSid: "OWNER",
       status: "ACTIVE",
       extra: "x"
     }
@@ -55,11 +55,11 @@ test("normalizeExecutionContext keeps actor payload generic", () => {
   assert.deepEqual(context.actor, {
     id: "user_1",
     email: "UPPER@EXAMPLE.COM",
-    roleId: "OWNER",
+    roleSid: "OWNER",
     customFlag: true
   });
   assert.deepEqual(context.membership, {
-    roleId: "OWNER",
+    roleSid: "OWNER",
     status: "ACTIVE",
     extra: "x"
   });

package/shared/support/crudLookup.js

@@ -64,7 +64,7 @@ function resolveCrudLookupContainerKey(resource = {}, options = {}) {
   return normalizeCrudLookupContainerKey(lookup?.containerKey, options);
 }
 
-function resolveCrudLookupFieldKeys(resource = {}, { allowKeys = [] } = {}) {
+function resolveCrudLookupFieldEntries(resource = {}, { allowKeys = [] } = {}) {
   const source = resource && typeof resource === "object" && !Array.isArray(resource) ? resource : {};
   const entries = Array.isArray(source.fieldMeta) ? source.fieldMeta : [];
   const allowedKeySet = new Set(
@@ -97,12 +97,67 @@ function resolveCrudLookupFieldKeys(resource = {}, { allowKeys = [] } = {}) {
     }
 
     seenKeys.add(key);
-    keys.push(key);
+    keys.push(
+      Object.freeze({
+        key,
+        parentRouteParamKey: normalizeText(entry.parentRouteParamKey)
+      })
+    );
   }
 
   return Object.freeze(keys);
 }
 
+function resolveCrudLookupCreateSchemaKeys(resource = {}) {
+  const createSchemaProperties = resource?.operations?.create?.bodyValidator?.schema?.properties;
+  if (!createSchemaProperties || typeof createSchemaProperties !== "object" || Array.isArray(createSchemaProperties)) {
+    return Object.freeze([]);
+  }
+
+  return Object.freeze(Object.keys(createSchemaProperties));
+}
+
+function resolveCrudLookupFieldKeys(resource = {}, { allowKeys = [] } = {}) {
+  return Object.freeze(
+    resolveCrudLookupFieldEntries(resource, { allowKeys })
+      .map(({ key }) => key)
+  );
+}
+
+function resolveCrudParentFilterKeys(resource = {}) {
+  return resolveCrudLookupFieldKeys(resource, {
+    allowKeys: resolveCrudLookupCreateSchemaKeys(resource)
+  });
+}
+
+function resolveCrudLookupFieldKeyFromRouteParam(resource = {}, routeParamKey = "", { allowKeys = [] } = {}) {
+  const normalizedRouteParamKey = normalizeText(routeParamKey);
+  if (!normalizedRouteParamKey) {
+    return "";
+  }
+
+  const entries = resolveCrudLookupFieldEntries(resource, { allowKeys });
+  for (const entry of entries) {
+    if (entry.key === normalizedRouteParamKey) {
+      return entry.key;
+    }
+  }
+
+  for (const entry of entries) {
+    if (entry.parentRouteParamKey === normalizedRouteParamKey) {
+      return entry.key;
+    }
+  }
+
+  return "";
+}
+
+function resolveCrudParentFilterFieldKeyFromRouteParam(resource = {}, routeParamKey = "") {
+  return resolveCrudLookupFieldKeyFromRouteParam(resource, routeParamKey, {
+    allowKeys: resolveCrudLookupCreateSchemaKeys(resource)
+  });
+}
+
 export {
   DEFAULT_CRUD_LOOKUP_CONTAINER_KEY,
   normalizeCrudLookupApiPath,
@@ -110,5 +165,8 @@ export {
   resolveCrudLookupApiPathFromNamespace,
   normalizeCrudLookupContainerKey,
   resolveCrudLookupContainerKey,
-  resolveCrudLookupFieldKeys
+  resolveCrudLookupFieldKeys,
+  resolveCrudParentFilterKeys,
+  resolveCrudLookupFieldKeyFromRouteParam,
+  resolveCrudParentFilterFieldKeyFromRouteParam
 };

package/shared/support/crudLookup.test.js

@@ -7,7 +7,10 @@ import {
   resolveCrudLookupApiPathFromNamespace,
   normalizeCrudLookupContainerKey,
   resolveCrudLookupContainerKey,
-  resolveCrudLookupFieldKeys
+  resolveCrudParentFilterKeys,
+  resolveCrudLookupFieldKeys,
+  resolveCrudLookupFieldKeyFromRouteParam,
+  resolveCrudParentFilterFieldKeyFromRouteParam
 } from "./crudLookup.js";
 
 test("normalizeCrudLookupApiPath normalizes and rejects root", () => {
@@ -69,6 +72,7 @@ test("resolveCrudLookupFieldKeys returns lookup field keys with optional allow-l
       },
       {
         key: "vetId",
+        parentRouteParamKey: "primaryVetId",
         relation: {
           kind: "lookup",
           apiPath: "/vets",
@@ -81,3 +85,139 @@ test("resolveCrudLookupFieldKeys returns lookup field keys with optional allow-l
   assert.deepEqual(resolveCrudLookupFieldKeys(resource), ["contactId", "vetId"]);
   assert.deepEqual(resolveCrudLookupFieldKeys(resource, { allowKeys: ["vetId", "missing"] }), ["vetId"]);
 });
+
+test("resolveCrudLookupFieldKeyFromRouteParam matches parent route param aliases to canonical lookup field keys", () => {
+  const resource = {
+    fieldMeta: [
+      {
+        key: "staffContactId",
+        parentRouteParamKey: "contactId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/contacts",
+          valueKey: "id"
+        }
+      },
+      {
+        key: "serviceId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/services",
+          valueKey: "id"
+        }
+      }
+    ]
+  };
+
+  assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "contactId"), "staffContactId");
+  assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "staffContactId"), "staffContactId");
+  assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "serviceId"), "serviceId");
+  assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "unknown"), "");
+  assert.equal(
+    resolveCrudLookupFieldKeyFromRouteParam(resource, "contactId", { allowKeys: ["serviceId"] }),
+    ""
+  );
+});
+
+test("resolveCrudLookupFieldKeyFromRouteParam prefers exact field keys before alias matches", () => {
+  const resource = {
+    fieldMeta: [
+      {
+        key: "staffContactId",
+        parentRouteParamKey: "contactId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/contacts",
+          valueKey: "id"
+        }
+      },
+      {
+        key: "contactId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/contacts",
+          valueKey: "id"
+        }
+      }
+    ]
+  };
+
+  assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "contactId"), "contactId");
+});
+
+test("resolveCrudParentFilterKeys keeps only lookup keys that are writable through create", () => {
+  const resource = {
+    operations: {
+      create: {
+        bodyValidator: {
+          schema: {
+            type: "object",
+            properties: {
+              serviceId: { type: "integer" }
+            }
+          }
+        }
+      }
+    },
+    fieldMeta: [
+      {
+        key: "staffContactId",
+        parentRouteParamKey: "contactId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/contacts",
+          valueKey: "id"
+        }
+      },
+      {
+        key: "serviceId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/services",
+          valueKey: "id"
+        }
+      }
+    ]
+  };
+
+  assert.deepEqual(resolveCrudParentFilterKeys(resource), ["serviceId"]);
+});
+
+test("resolveCrudParentFilterFieldKeyFromRouteParam uses the same allowed keys as server parent filters", () => {
+  const resource = {
+    operations: {
+      create: {
+        bodyValidator: {
+          schema: {
+            type: "object",
+            properties: {
+              serviceId: { type: "integer" }
+            }
+          }
+        }
+      }
+    },
+    fieldMeta: [
+      {
+        key: "staffContactId",
+        parentRouteParamKey: "contactId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/contacts",
+          valueKey: "id"
+        }
+      },
+      {
+        key: "serviceId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/services",
+          valueKey: "id"
+        }
+      }
+    ]
+  };
+
+  assert.equal(resolveCrudParentFilterFieldKeyFromRouteParam(resource, "contactId"), "");
+  assert.equal(resolveCrudParentFilterFieldKeyFromRouteParam(resource, "serviceId"), "serviceId");
+});

package/shared/support/normalize.js

@@ -3,6 +3,18 @@ function normalizeText(value, { fallback = "" } = {}) {
   return normalized || fallback;
 }
 
+function hasValue(value) {
+  if (value == null) {
+    return false;
+  }
+
+  if (typeof value === "string") {
+    return normalizeText(value).length > 0;
+  }
+
+  return true;
+}
+
 function normalizeBoolean(value) {
   if (typeof value === "boolean") {
     return value;
@@ -88,7 +100,31 @@ function normalizeIfInSource(source, normalized, fieldName, normalizer = (value)
     return normalized;
   }
 
-  normalized[normalizedFieldName] = normalizer(sourceValue);
+  try {
+    normalized[normalizedFieldName] = normalizer(sourceValue);
+  } catch (error) {
+    const normalizedMessage = normalizeText(error?.message, {
+      fallback: `${normalizedFieldName} is invalid.`
+    });
+    const sourceDetails = isRecord(error?.details) ? error.details : {};
+    const sourceFieldErrors = isRecord(error?.fieldErrors)
+      ? { ...error.fieldErrors }
+      : isRecord(sourceDetails.fieldErrors)
+        ? { ...sourceDetails.fieldErrors }
+        : {};
+
+    if (!normalizeText(sourceFieldErrors[normalizedFieldName])) {
+      sourceFieldErrors[normalizedFieldName] = normalizedMessage;
+    }
+
+    const normalizedError = error instanceof Error ? error : new Error(normalizedMessage);
+    normalizedError.fieldErrors = sourceFieldErrors;
+    normalizedError.details = {
+      ...sourceDetails,
+      fieldErrors: sourceFieldErrors
+    };
+    throw normalizedError;
+  }
   return normalized;
 }
 
@@ -193,6 +229,7 @@ function ensureNonEmptyText(value, label = "value") {
 
 export {
   normalizeText,
+  hasValue,
   normalizeBoolean,
   normalizeFiniteNumber,
   normalizeFiniteInteger,

package/shared/support/normalize.test.js

@@ -1,6 +1,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import {
+  hasValue,
   normalizeBoolean,
   normalizeFiniteInteger,
   normalizeFiniteNumber,
@@ -15,6 +16,19 @@ import {
   normalizeUniqueTextList
 } from "./normalize.js";
 
+test("hasValue returns false for nullish and blank text, true otherwise", () => {
+  assert.equal(hasValue(null), false);
+  assert.equal(hasValue(undefined), false);
+  assert.equal(hasValue(""), false);
+  assert.equal(hasValue("   "), false);
+  assert.equal(hasValue("0"), true);
+  assert.equal(hasValue("-"), true);
+  assert.equal(hasValue(0), true);
+  assert.equal(hasValue(false), true);
+  assert.equal(hasValue([]), true);
+  assert.equal(hasValue({}), true);
+});
+
 test("normalizeQueryToken trims, lowercases, and falls back when empty", () => {
   assert.equal(normalizeQueryToken("  Admin  "), "admin");
   assert.equal(normalizeQueryToken(""), "__none__");
@@ -100,6 +114,29 @@ test("normalizeIfInSource passes through nullish values without normalizer", ()
   });
 });
 
+test("normalizeIfInSource annotates thrown normalizer errors with fieldErrors", () => {
+  const source = {
+    temperament: "unknowne"
+  };
+  const normalized = {};
+
+  assert.throws(
+    () =>
+      normalizeIfInSource(source, normalized, "temperament", () => {
+        throw new Error("Invalid pet temperament \"unknowne\".");
+      }),
+    (error) => {
+      assert.deepEqual(error?.fieldErrors, {
+        temperament: "Invalid pet temperament \"unknowne\"."
+      });
+      assert.deepEqual(error?.details?.fieldErrors, {
+        temperament: "Invalid pet temperament \"unknowne\"."
+      });
+      return true;
+    }
+  );
+});
+
 test("normalizeIfInSource validates target and function arguments", () => {
   assert.throws(
     () => normalizeIfInSource({ firstName: "Ada" }, null, "firstName", normalizeText),

package/shared/validators/cursorPaginationQueryValidator.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { normalizeText } from "../support/normalize.js";
 import { normalizeObjectInput } from "./inputNormalization.js";
 import { positiveIntegerValidator } from "./recordIdParamsValidator.js";
 
@@ -7,7 +8,7 @@ function normalizeCursorPaginationQuery(input = {}) {
   const normalized = {};
 
   if (Object.hasOwn(source, "cursor")) {
-    normalized.cursor = positiveIntegerValidator.normalize(source.cursor);
+    normalized.cursor = normalizeText(source.cursor);
   }
 
   if (Object.hasOwn(source, "limit")) {

package/shared/validators/cursorPaginationQueryValidator.test.js

@@ -2,18 +2,20 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { cursorPaginationQueryValidator } from "./cursorPaginationQueryValidator.js";
 
-test("cursorPaginationQueryValidator normalizes numeric strings", () => {
+test("cursorPaginationQueryValidator normalizes numeric strings as cursor text", () => {
   assert.deepEqual(cursorPaginationQueryValidator.normalize({ cursor: "12", limit: "25" }), {
-    cursor: 12,
+    cursor: "12",
     limit: 25
   });
 });
 
-test("cursorPaginationQueryValidator normalizes invalid values to 0", () => {
-  assert.deepEqual(cursorPaginationQueryValidator.normalize({ cursor: "abc", limit: "-1" }), {
-    cursor: 0,
-    limit: 0
-  });
+test("cursorPaginationQueryValidator schema rejects opaque cursor strings", () => {
+  assert.equal(
+    cursorPaginationQueryValidator.schema.properties.cursor.anyOf.some(
+      (entry) => entry.type === "string" && entry.pattern === "^[1-9][0-9]*$"
+    ),
+    true
+  );
 });
 
 test("cursorPaginationQueryValidator keeps absent keys absent", () => {

package/shared/validators/htmlTimeSchemas.js

@@ -0,0 +1,13 @@
+import { Type } from "typebox";
+
+const HTML_TIME_STRING_SCHEMA = Type.String({
+  pattern: "^(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d)?$",
+  minLength: 5
+});
+
+const NULLABLE_HTML_TIME_STRING_SCHEMA = Type.Union([HTML_TIME_STRING_SCHEMA, Type.Null()]);
+
+export {
+  HTML_TIME_STRING_SCHEMA,
+  NULLABLE_HTML_TIME_STRING_SCHEMA
+};

package/shared/validators/index.js

@@ -1,6 +1,10 @@
 export { normalizeObjectInput } from "./inputNormalization.js";
 export { createCursorListValidator } from "./createCursorListValidator.js";
 export { cursorPaginationQueryValidator } from "./cursorPaginationQueryValidator.js";
+export {
+  HTML_TIME_STRING_SCHEMA,
+  NULLABLE_HTML_TIME_STRING_SCHEMA
+} from "./htmlTimeSchemas.js";
 export { mergeObjectSchemas } from "./mergeObjectSchemas.js";
 export { mergeValidators } from "./mergeValidators.js";
 export { nestValidator } from "./nestValidator.js";