@jskit-ai/kernel 0.1.32 → 0.1.33

package/package.json

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

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

@@ -236,7 +236,7 @@ test("registerRoutes attaches visibilityContext from route visibility resolvers"
       }
 
       return {
-        userOwnerId: context?.actor?.id,
+        userId: context?.actor?.id,
         requiresActorScope: true
       };
     }
@@ -281,7 +281,7 @@ test("registerRoutes attaches visibilityContext from route visibility resolvers"
     scopeKind: null,
     requiresActorScope: true,
     scopeOwnerId: null,
-    userOwnerId: 23
+    userId: "23"
   });
   assert.deepEqual(observed[0].context.requestMeta.visibilityContext, observed[0].context.visibilityContext);
   assert.equal(observed[0].context.requestMeta.routeVisibility, "user");
@@ -309,7 +309,7 @@ test("registerRoutes keeps actor scope requirement for core user visibility with
       }
 
       return {
-        userOwnerId: context?.actor?.id
+        userId: context?.actor?.id
       };
     }
   }));
@@ -353,7 +353,7 @@ test("registerRoutes keeps actor scope requirement for core user visibility with
     scopeKind: null,
     requiresActorScope: true,
     scopeOwnerId: null,
-    userOwnerId: 23
+    userId: "23"
   });
   assert.equal(observed[0].context.requestMeta.routeVisibility, "user");
 });
@@ -399,7 +399,7 @@ test("registerRoutes does not infer actor scope from non-core route visibility t
     scopeKind: null,
     requiresActorScope: false,
     scopeOwnerId: null,
-    userOwnerId: null
+    userId: null
   });
   assert.equal(observed[0].context.requestMeta.routeVisibility, "workspace_user");
 });

package/server/runtime/entityChangeEvents.js

@@ -43,10 +43,10 @@ function resolveVisibilityScope(visibilityContext = {}, runtimeContext = {}) {
   const visibility = normalizeText(visibilityContext.visibility).toLowerCase();
   const scopeKind = normalizeText(visibilityContext.scopeKind || visibility).toLowerCase();
   const scopeOwnerId = normalizeOpaqueId(visibilityContext.scopeOwnerId);
-  const userOwnerId = normalizeOpaqueId(visibilityContext.userOwnerId);
+  const userId = normalizeOpaqueId(visibilityContext.userId);
   const requiresActorScope = visibilityContext.requiresActorScope === true;
 
-  if (requiresActorScope && userOwnerId == null) {
+  if (requiresActorScope && userId == null) {
     return null;
   }
 
@@ -57,7 +57,7 @@ function resolveVisibilityScope(visibilityContext = {}, runtimeContext = {}) {
     };
     if (requiresActorScope) {
       scope.scopeId = scopeOwnerId;
-      scope.userId = userOwnerId;
+      scope.userId = userId;
     }
     return scope;
   }
@@ -72,10 +72,10 @@ function resolveVisibilityScope(visibilityContext = {}, runtimeContext = {}) {
     };
   }
 
-  if (scopeKind === "user" && userOwnerId != null) {
+  if (scopeKind === "user" && userId != null) {
     return {
       kind: "user",
-      id: userOwnerId
+      id: userId
     };
   }
 

package/server/runtime/entityChangeEvents.test.js

@@ -33,9 +33,9 @@ test("entity change publisher emits normalized event payload", async () => {
   });
 
   assert.equal(payload?.operation, "created");
-  assert.equal(payload?.entityId, 5);
-  assert.deepEqual(payload?.scope, { kind: "scope", id: 23 });
-  assert.equal(payload?.actorId, 17);
+  assert.equal(payload?.entityId, "5");
+  assert.deepEqual(payload?.scope, { kind: "scope", id: "23" });
+  assert.equal(payload?.actorId, "17");
   assert.equal(payload?.commandId, "cmd-1");
   assert.equal(payload?.sourceClientId, "client-a");
   assert.equal(payload?.meta?.service?.token, "crud.customers");
@@ -111,7 +111,7 @@ test("entity change publisher infers scoped owner from service context when visi
     }
   );
 
-  assert.deepEqual(payload?.scope, { kind: "workspace", id: 23 });
+  assert.deepEqual(payload?.scope, { kind: "workspace", id: "23" });
   assert.equal(published.length, 1);
 });
 
@@ -133,7 +133,7 @@ test("entity change publisher supports opaque actor and scope identifiers", asyn
       visibilityContext: {
         scopeKind: "workspace_user",
         scopeOwnerId: "workspace_23",
-        userOwnerId: "user_17",
+        userId: "user_17",
         requiresActorScope: true
       }
     }

package/server/runtime/serviceAuthorization.test.js

@@ -24,7 +24,7 @@ test("requireAuth accepts actor context", () => {
     }
   });
 
-  assert.equal(actor.id, 7);
+  assert.equal(actor.id, "7");
 });
 
 test("requireAuth accepts non-numeric actor ids", () => {

package/shared/support/normalize.js

@@ -180,6 +180,34 @@ function normalizePositiveInteger(value, { fallback = 0 } = {}) {
   return numeric;
 }
 
+function normalizeCanonicalRecordIdText(value, { fallback = null } = {}) {
+  if (value == null) {
+    return fallback;
+  }
+
+  const normalized = String(value).trim();
+  return /^[1-9][0-9]*$/.test(normalized) ? normalized : fallback;
+}
+
+function normalizeRecordId(value, { fallback = null } = {}) {
+  if (value == null) {
+    return fallback;
+  }
+
+  if (typeof value === "string") {
+    return normalizeCanonicalRecordIdText(value, { fallback });
+  }
+
+  if (typeof value === "bigint") {
+    if (value < 1n) {
+      return fallback;
+    }
+    return normalizeCanonicalRecordIdText(value, { fallback });
+  }
+
+  return fallback;
+}
+
 function normalizeOpaqueId(value, { fallback = null } = {}) {
   if (value == null) {
     return fallback;
@@ -191,7 +219,7 @@ function normalizeOpaqueId(value, { fallback = null } = {}) {
   }
 
   if (typeof value === "number") {
-    return Number.isFinite(value) ? value : fallback;
+    return Number.isFinite(value) ? String(value) : fallback;
   }
 
   if (typeof value === "bigint") {
@@ -244,6 +272,8 @@ export {
   normalizeUniqueTextList,
   normalizeInteger,
   normalizePositiveInteger,
+  normalizeCanonicalRecordIdText,
+  normalizeRecordId,
   normalizeOpaqueId,
   normalizeOneOf,
   ensureNonEmptyText

package/shared/support/normalize.test.js

@@ -3,11 +3,13 @@ import assert from "node:assert/strict";
 import {
   hasValue,
   normalizeBoolean,
+  normalizeCanonicalRecordIdText,
   normalizeFiniteInteger,
   normalizeFiniteNumber,
   normalizeIfInSource,
   normalizeIfPresent,
   normalizeOrNull,
+  normalizeRecordId,
   normalizeOpaqueId,
   normalizePositiveInteger,
   normalizeOneOf,
@@ -172,10 +174,27 @@ test("normalizeOrNull normalizes non-nullish values and coerces nullish to null"
   );
 });
 
+test("normalizeRecordId accepts canonical string and bigint identifiers only", () => {
+  const unsafeNumericId = Number(9007199254740993n);
+  assert.equal(normalizeRecordId("  7  "), "7");
+  assert.equal(normalizeRecordId(10n), "10");
+  assert.equal(normalizeRecordId(7), null);
+  assert.equal(normalizeRecordId(unsafeNumericId), null);
+  assert.equal(normalizeRecordId(""), null);
+  assert.equal(normalizeRecordId(null), null);
+});
+
+test("normalizeCanonicalRecordIdText validates canonical positive decimal identifiers", () => {
+  assert.equal(normalizeCanonicalRecordIdText("  7  "), "7");
+  assert.equal(normalizeCanonicalRecordIdText("007"), null);
+  assert.equal(normalizeCanonicalRecordIdText("0"), null);
+  assert.equal(normalizeCanonicalRecordIdText("abc"), null);
+});
+
 test("normalizeOpaqueId preserves opaque identifiers", () => {
   assert.equal(normalizeOpaqueId("  user-123  "), "user-123");
-  assert.equal(normalizeOpaqueId(7), 7);
-  assert.equal(normalizeOpaqueId(0), 0);
+  assert.equal(normalizeOpaqueId(7), "7");
+  assert.equal(normalizeOpaqueId(0), "0");
   assert.equal(normalizeOpaqueId(10n), "10");
   assert.equal(normalizeOpaqueId(""), null);
   assert.equal(normalizeOpaqueId(null), null);

package/shared/support/visibility.js

@@ -49,7 +49,7 @@ function normalizeVisibilityContext(value = {}) {
     scopeKind: normalizedScopeKind,
     requiresActorScope: source.requiresActorScope === true,
     scopeOwnerId: normalizeOpaqueId(source.scopeOwnerId),
-    userOwnerId: normalizeOpaqueId(source.userOwnerId)
+    userId: normalizeOpaqueId(source.userId)
   });
 }
 

package/shared/support/visibility.test.js

@@ -19,20 +19,20 @@ test("normalizeRouteVisibilityToken normalizes visibility tokens for module-leve
 });
 
 test("normalizeVisibilityContext normalizes mode and owner identifiers", () => {
-  assert.deepEqual(normalizeVisibilityContext({ visibility: "user", userOwnerId: "7" }), {
+  assert.deepEqual(normalizeVisibilityContext({ visibility: "user", userId: "7" }), {
     visibility: "user",
     scopeKind: null,
     requiresActorScope: false,
     scopeOwnerId: null,
-    userOwnerId: "7"
+    userId: "7"
   });
 
-  assert.deepEqual(normalizeVisibilityContext({ visibility: "workspace_user", scopeOwnerId: "4", userOwnerId: 9 }), {
+  assert.deepEqual(normalizeVisibilityContext({ visibility: "workspace_user", scopeOwnerId: "4", userId: 9 }), {
     visibility: "workspace_user",
     scopeKind: null,
     requiresActorScope: false,
     scopeOwnerId: "4",
-    userOwnerId: 9
+    userId: "9"
   });
 
   assert.deepEqual(normalizeVisibilityContext({ visibility: "workspace", scopeOwnerId: "0" }), {
@@ -40,6 +40,6 @@ test("normalizeVisibilityContext normalizes mode and owner identifiers", () => {
     scopeKind: null,
     requiresActorScope: false,
     scopeOwnerId: "0",
-    userOwnerId: null
+    userId: null
   });
 });

package/shared/validators/cursorPaginationQueryValidator.js

@@ -1,14 +1,13 @@
 import { Type } from "typebox";
-import { normalizeText } from "../support/normalize.js";
 import { normalizeObjectInput } from "./inputNormalization.js";
-import { positiveIntegerValidator } from "./recordIdParamsValidator.js";
+import { positiveIntegerValidator, recordIdInputSchema, recordIdValidator } from "./recordIdParamsValidator.js";
 
 function normalizeCursorPaginationQuery(input = {}) {
   const source = normalizeObjectInput(input);
   const normalized = {};
 
   if (Object.hasOwn(source, "cursor")) {
-    normalized.cursor = normalizeText(source.cursor);
+    normalized.cursor = recordIdValidator.normalize(source.cursor);
   }
 
   if (Object.hasOwn(source, "limit")) {
@@ -21,7 +20,7 @@ function normalizeCursorPaginationQuery(input = {}) {
 const cursorPaginationQueryValidator = Object.freeze({
   schema: Type.Object(
     {
-      cursor: Type.Optional(positiveIntegerValidator.schema),
+      cursor: Type.Optional(recordIdInputSchema),
       limit: Type.Optional(positiveIntegerValidator.schema)
     },
     { additionalProperties: false }

package/shared/validators/cursorPaginationQueryValidator.test.js

@@ -11,9 +11,8 @@ test("cursorPaginationQueryValidator normalizes numeric strings as cursor text",
 
 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]*$"
-    ),
+    cursorPaginationQueryValidator.schema.properties.cursor.type === "string" &&
+      cursorPaginationQueryValidator.schema.properties.cursor.pattern === "^[1-9][0-9]*$",
     true
   );
 });

package/shared/validators/index.js

@@ -8,7 +8,17 @@ export {
 export { mergeObjectSchemas } from "./mergeObjectSchemas.js";
 export { mergeValidators } from "./mergeValidators.js";
 export { nestValidator } from "./nestValidator.js";
-export { recordIdParamsValidator, positiveIntegerValidator } from "./recordIdParamsValidator.js";
+export {
+  RECORD_ID_PATTERN,
+  recordIdSchema,
+  recordIdInputSchema,
+  nullableRecordIdSchema,
+  nullableRecordIdInputSchema,
+  recordIdValidator,
+  nullableRecordIdValidator,
+  recordIdParamsValidator,
+  positiveIntegerValidator
+} from "./recordIdParamsValidator.js";
 export { normalizeSettingsFieldInput, normalizeSettingsFieldOutput } from "./settingsFieldNormalization.js";
 export {
   normalizeRequiredFieldList,

package/shared/validators/recordIdParamsValidator.js

@@ -1,23 +1,51 @@
 import { Type } from "typebox";
 import { normalizeObjectInput } from "./inputNormalization.js";
-import { normalizePositiveInteger, normalizeText } from "../support/normalize.js";
+import { normalizePositiveInteger, normalizeRecordId } from "../support/normalize.js";
 
-function normalizeRecordId(value) {
-  return normalizePositiveInteger(normalizeText(value));
-}
+const RECORD_ID_PATTERN = "^[1-9][0-9]*$";
+
+const recordIdSchema = Type.String({
+  minLength: 1,
+  pattern: RECORD_ID_PATTERN
+});
+
+const recordIdInputSchema = recordIdSchema;
+
+const nullableRecordIdSchema = Type.Union([recordIdSchema, Type.Null()]);
+const nullableRecordIdInputSchema = Type.Union([recordIdInputSchema, Type.Null()]);
 
 const positiveIntegerValidator = Object.freeze({
   schema: Type.Union([
     Type.Integer({ minimum: 1 }),
-    Type.String({ minLength: 1, pattern: "^[1-9][0-9]*$" })
+    Type.String({ minLength: 1, pattern: RECORD_ID_PATTERN })
   ]),
-  normalize: normalizeRecordId
+  normalize(value) {
+    return normalizePositiveInteger(value);
+  }
+});
+
+const recordIdValidator = Object.freeze({
+  schema: recordIdInputSchema,
+  normalize(value) {
+    return normalizeRecordId(value, {
+      fallback: ""
+    });
+  }
+});
+
+const nullableRecordIdValidator = Object.freeze({
+  schema: nullableRecordIdInputSchema,
+  normalize(value) {
+    return normalizeRecordId(value, {
+      fallback: null
+    });
+  }
 });
 
 const recordIdParamsValidator = Object.freeze({
   schema: Type.Object(
     {
-      recordId: Type.Optional(positiveIntegerValidator.schema)
+      recordId: Type.Optional(recordIdInputSchema)
     },
     { additionalProperties: false }
   ),
@@ -26,11 +54,21 @@ const recordIdParamsValidator = Object.freeze({
     const normalized = {};
 
     if (Object.hasOwn(source, "recordId")) {
-      normalized.recordId = normalizeRecordId(source.recordId);
+      normalized.recordId = recordIdValidator.normalize(source.recordId);
     }
 
     return normalized;
   }
 });
 
-export { recordIdParamsValidator, positiveIntegerValidator };
+export {
+  RECORD_ID_PATTERN,
+  recordIdSchema,
+  recordIdInputSchema,
+  nullableRecordIdSchema,
+  nullableRecordIdInputSchema,
+  recordIdValidator,
+  nullableRecordIdValidator,
+  recordIdParamsValidator,
+  positiveIntegerValidator
+};

package/shared/validators/recordIdParamsValidator.test.js

@@ -3,15 +3,18 @@ import assert from "node:assert/strict";
 
 import { recordIdParamsValidator } from "./recordIdParamsValidator.js";
 
-test("recordIdParamsValidator normalizes string id to positive integer", () => {
+test("recordIdParamsValidator normalizes canonical string ids", () => {
   assert.deepEqual(recordIdParamsValidator.normalize({ recordId: "42" }), {
-    recordId: 42
+    recordId: "42"
   });
 });
 
-test("recordIdParamsValidator normalizes invalid id to 0", () => {
+test("recordIdParamsValidator rejects invalid ids", () => {
   assert.deepEqual(recordIdParamsValidator.normalize({ recordId: "nope" }), {
-    recordId: 0
+    recordId: ""
+  });
+  assert.deepEqual(recordIdParamsValidator.normalize({ recordId: 42 }), {
+    recordId: ""
   });
 });