@jskit-ai/kernel 0.1.245 → 0.1.246

package/internal/node/installedPackages.js

@@ -1,8 +1,8 @@
-import { readFile, realpath } from "node:fs/promises";
+import { realpath } from "node:fs/promises";
 import path from "node:path";
 import { normalizeObject } from "../../shared/support/normalize.js";
 import { sortStrings } from "../../shared/support/sorting.js";
-import { fileExists } from "./fileSystem.js";
+import { fileExists, readJsonFile } from "./fileSystem.js";
 
 const ROOT_DEPENDENCY_SECTIONS = Object.freeze([
   "dependencies",
@@ -18,14 +18,6 @@ const JSKIT_PACKAGE_CONFIG_KEYS = Object.freeze([
   "vite"
 ]);
 
-async function readJsonFile(filePath, fallback = {}) {
-  try {
-    return JSON.parse(await readFile(filePath, "utf8"));
-  } catch {
-    return fallback;
-  }
-}
-
 function collectRootDependencySpecifiers(packageJson = {}) {
   const specifiers = new Map();
   for (const sectionName of ROOT_DEPENDENCY_SECTIONS) {
@@ -42,7 +34,7 @@ function collectRootDependencySpecifiers(packageJson = {}) {
 
 function collectPackageDependencyIds(packageJson = {}) {
   const dependencyIds = new Set();
-  for (const sectionName of ["dependencies", "optionalDependencies", "peerDependencies"]) {
+  for (const sectionName of ROOT_DEPENDENCY_SECTIONS) {
     for (const packageId of Object.keys(normalizeObject(packageJson?.[sectionName]))) {
       const normalizedPackageId = String(packageId || "").trim();
       if (normalizedPackageId) {
@@ -175,56 +167,27 @@ async function discoverInstalledPackages({ appRoot } = {}) {
   const rootPackageJson = await readJsonFile(path.resolve(normalizedAppRoot, "package.json"), {});
   const directSpecifiers = collectRootDependencySpecifiers(rootPackageJson);
   const directPackageIds = new Set(directSpecifiers.keys());
-  const runtimeRootPackageIds = new Set(
-    ["dependencies", "optionalDependencies", "peerDependencies"]
-      .flatMap((sectionName) => Object.keys(normalizeObject(rootPackageJson?.[sectionName])))
-  );
   const visited = new Set();
+  // Breadth-first walk of the dependency graph; the queue stays ordered by packageId.
   const queue = [];
-  const queued = new Map();
+  const queued = new Set();
   const packages = [];
 
-  const sortQueue = () => {
-    queue.sort((left, right) => {
-      if (left.traverseDependencies !== right.traverseDependencies) {
-        return left.traverseDependencies ? -1 : 1;
-      }
-      return left.packageId.localeCompare(right.packageId);
-    });
-  };
-  const enqueue = ({ packageId, parentPackageRoot = "", traverseDependencies = false }) => {
-    const normalizedPackageId = String(packageId || "").trim();
-    if (!normalizedPackageId || visited.has(normalizedPackageId)) {
-      return;
-    }
-    const existing = queued.get(normalizedPackageId);
-    if (existing) {
-      if (traverseDependencies && !existing.traverseDependencies) {
-        existing.traverseDependencies = true;
-        existing.parentPackageRoot = parentPackageRoot || existing.parentPackageRoot;
-        sortQueue();
-      }
+  const enqueue = ({ packageId, parentPackageRoot = "" }) => {
+    if (!packageId || visited.has(packageId) || queued.has(packageId)) {
       return;
     }
-    const entry = {
-      packageId: normalizedPackageId,
-      parentPackageRoot,
-      traverseDependencies: Boolean(traverseDependencies)
-    };
-    queue.push(entry);
-    queued.set(normalizedPackageId, entry);
-    sortQueue();
+    queue.push({ packageId, parentPackageRoot });
+    queued.add(packageId);
+    queue.sort((left, right) => left.packageId.localeCompare(right.packageId));
   };
 
   for (const packageId of sortStrings([...directPackageIds])) {
-    enqueue({
-      packageId,
-      traverseDependencies: runtimeRootPackageIds.has(packageId)
-    });
+    enqueue({ packageId });
   }
 
   while (queue.length > 0) {
-    const { packageId, parentPackageRoot, traverseDependencies } = queue.shift();
+    const { packageId, parentPackageRoot } = queue.shift();
     queued.delete(packageId);
     if (!packageId || visited.has(packageId)) {
       continue;
@@ -252,15 +215,8 @@ async function discoverInstalledPackages({ appRoot } = {}) {
     }
 
     const dependencyIds = collectPackageDependencyIds(packageJson);
-    if (traverseDependencies) {
-      for (const dependencyId of dependencyIds) {
-        const normalizedDependencyId = String(dependencyId || "").trim();
-        enqueue({
-          packageId: normalizedDependencyId,
-          parentPackageRoot: roots.packageRoot,
-          traverseDependencies: true
-        });
-      }
+    for (const dependencyId of dependencyIds) {
+      enqueue({ packageId: dependencyId, parentPackageRoot: roots.packageRoot });
     }
 
     const packageMetadata = createPackageMetadata(packageJson);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.245",
+  "version": "0.1.246",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "^1.0.17"
@@ -25,18 +25,16 @@
     "./client/moduleBootstrap": "./client/moduleBootstrap.js",
     "./client/vite": "./client/vite/index.js",
     "./server/actions": "./server/actions/index.js",
+    "./server/actions/actionContributorHelpers": "./server/actions/actionContributorHelpers.js",
     "./server/features": "./server/features/index.js",
     "./server/http": "./server/http/index.js",
     "./server/platform": "./server/platform/index.js",
     "./server/runtime": "./server/runtime/index.js",
-    "./server/runtime/entityChangeEvents": "./server/runtime/entityChangeEvents.js",
     "./server/runtime/errors": "./server/runtime/errors.js",
     "./server/runtime/requestUrl": "./server/runtime/requestUrl.js",
     "./server/support": "./server/support/index.js",
     "./shared": "./shared/index.js",
     "./shared/capabilities": "./shared/capabilities/index.js",
-    "./shared/actions/actionContributorHelpers": "./shared/actions/actionContributorHelpers.js",
-    "./shared/actions/textNormalization": "./shared/actions/textNormalization.js",
     "./shared/validators": "./shared/validators/index.js",
     "./shared/validators/inputNormalization": "./shared/validators/inputNormalization.js",
     "./shared/support": "./shared/support/index.js",

package/server/actions/actionCatalogue.js

@@ -1,4 +1,4 @@
-import { createActionRegistry } from "../../shared/actions/registry.js";
+import { createActionRegistry } from "./registry.js";
 import { isRecord } from "../../shared/support/normalize.js";
 
 function normalizeRegistration(value) {
@@ -9,21 +9,12 @@ function normalizeRegistration(value) {
   return value;
 }
 
-function createActionCatalogue({
-  idempotencyAdapter,
-  auditAdapter,
-  observabilityAdapter,
-  events,
-  logger = null
-} = {}) {
+function createActionCatalogue({ events, logger = null } = {}) {
   const contributors = [];
   const contextContributors = [];
   const contextContributorIds = new Set();
   let registry = createActionRegistry({
     contributors,
-    idempotencyAdapter,
-    auditAdapter,
-    observabilityAdapter,
     events,
     logger
   });
@@ -36,9 +27,6 @@ function createActionCatalogue({
     const nextContributors = [...contributors, normalizeRegistration(contributor)];
     const nextRegistry = createActionRegistry({
       contributors: nextContributors,
-      idempotencyAdapter,
-      auditAdapter,
-      observabilityAdapter,
       events,
       logger
     });
@@ -104,40 +92,31 @@ function createActionCatalogue({
     return Object.freeze(enriched);
   }
 
-  async function execute(payload = {}) {
+  async function run(method, payload = {}) {
     const source = payload && typeof payload === "object" ? payload : {};
     const input = source.input && typeof source.input === "object" ? source.input : {};
+    const version = source.version == null ? null : source.version;
     const context = await buildExecutionContext({
       actionId: source.actionId,
-      version: source.version == null ? null : source.version,
+      version,
       input,
       context: source.context
     });
-    return currentRegistry().execute({
+    return currentRegistry()[method]({
       actionId: source.actionId,
-      version: source.version == null ? null : source.version,
+      version,
       input,
       context,
       deps: isRecord(source.deps) ? source.deps : {}
     });
   }
 
-  async function executeStream(payload = {}) {
-    const source = payload && typeof payload === "object" ? payload : {};
-    const input = source.input && typeof source.input === "object" ? source.input : {};
-    const context = await buildExecutionContext({
-      actionId: source.actionId,
-      version: source.version == null ? null : source.version,
-      input,
-      context: source.context
-    });
-    return currentRegistry().executeStream({
-      actionId: source.actionId,
-      version: source.version == null ? null : source.version,
-      input,
-      context,
-      deps: isRecord(source.deps) ? source.deps : {}
-    });
+  function execute(payload) {
+    return run("execute", payload);
+  }
+
+  function executeStream(payload) {
+    return run("executeStream", payload);
   }
 
   function listDefinitions() {

package/{shared → server}/actions/actionContributorHelpers.js

@@ -1,6 +1,4 @@
 import { createSchema } from "json-rest-schema";
-import { normalizeObject, normalizePositiveInteger as toPositiveInteger } from "../support/normalize.js";
-import { hasPermission } from "../support/permissions.js";
 
 function requireServiceMethod(service, methodName, contributorId, { serviceLabel } = {}) {
   if (!service || typeof service[methodName] !== "function") {
@@ -19,10 +17,7 @@ const emptyInputValidator = Object.freeze({
 });
 
 export {
-  normalizeObject,
-  toPositiveInteger,
   requireServiceMethod,
   resolveRequest,
-  hasPermission,
   emptyInputValidator
 };

package/{shared → server}/actions/actionDefinitions.js

@@ -1,9 +1,7 @@
-import {
-  normalizeSingleSchemaDefinition
-} from "../validators/index.js";
-import { isRecord as isPlainObject, normalizePositiveInteger } from "../support/normalize.js";
-import { normalizePermissionList } from "../support/permissions.js";
-import { normalizeText } from "./textNormalization.js";
+import { normalizeSingleSchemaDefinition } from "../../shared/validators/index.js";
+import { isRecord as isPlainObject, normalizePositiveInteger, normalizeText } from "../../shared/support/normalize.js";
+import { normalizePermissionList } from "../../shared/support/permissions.js";
+import { ARCHITECTURE_ID_PATTERN } from "../../shared/capabilities/defineProvider.js";
 
 const ACTION_KINDS = Object.freeze(["query", "command", "stream"]);
 const ACTION_IDEMPOTENCY_POLICIES = Object.freeze(["none", "optional", "required", "domain_native"]);
@@ -12,7 +10,6 @@ const ACTION_PERMISSION_REQUIRE_MODES = Object.freeze(["none", "authenticated",
 const ACTION_KIND_SET = new Set(ACTION_KINDS);
 const ACTION_IDEMPOTENCY_SET = new Set(ACTION_IDEMPOTENCY_POLICIES);
 const ACTION_PERMISSION_REQUIRE_SET = new Set(ACTION_PERMISSION_REQUIRE_MODES);
-const ACTION_DOMAIN_PATTERN = /^[a-z][a-z0-9_.-]*$/;
 
 class ActionRuntimeError extends Error {
   constructor(status, message, options = {}) {
@@ -38,10 +35,10 @@ function normalizeActionDomain(value, { context = "domain", errorCode = "ACTION_
       code: errorCode
     });
   }
-  if (!ACTION_DOMAIN_PATTERN.test(domain)) {
+  if (!ARCHITECTURE_ID_PATTERN.test(domain)) {
     throw createActionRuntimeError(
       500,
-      `${context} must match ${ACTION_DOMAIN_PATTERN.toString()} (lowercase letters, digits, _, -, .).`,
+      `${context} must match ${ARCHITECTURE_ID_PATTERN.toString()} (lowercase letters, digits, _, -, .).`,
       {
         code: errorCode
       }
@@ -51,23 +48,13 @@ function normalizeActionDomain(value, { context = "domain", errorCode = "ACTION_
   return domain;
 }
 
-function normalizeStringArray(value, { fieldName, allowedSet, allowEmpty = false } = {}) {
+function normalizeStringArray(value, fieldName) {
   const source = Array.isArray(value) ? value : [];
   const normalized = Array.from(
-    new Set(
-      source
-        .map((entry) => normalizeText(entry).toLowerCase())
-        .filter(Boolean)
-        .filter((entry) => {
-          if (!(allowedSet instanceof Set)) {
-            return true;
-          }
-          return allowedSet.has(entry);
-        })
-    )
+    new Set(source.map((entry) => normalizeText(entry).toLowerCase()).filter(Boolean))
   );
 
-  if (!allowEmpty && normalized.length < 1) {
+  if (normalized.length < 1) {
     throw createActionRuntimeError(500, `Action definition ${fieldName} must include at least one value.`, {
       code: "ACTION_DEFINITION_INVALID"
     });
@@ -76,7 +63,7 @@ function normalizeStringArray(value, { fieldName, allowedSet, allowEmpty = false
   return normalized;
 }
 
-function normalizeSingleActionSchema(value, fieldName, { required = false, defaultMode = "" } = {}) {
+function normalizeActionSchema(value, fieldName, { required = false, defaultMode = "" } = {}) {
   if (value == null) {
     if (!required) {
       return null;
@@ -87,6 +74,12 @@ function normalizeSingleActionSchema(value, fieldName, { required = false, defau
     });
   }
 
+  if (Array.isArray(value)) {
+    throw createActionRuntimeError(500, `Action definition ${fieldName} must be a single schema definition.`, {
+      code: "ACTION_DEFINITION_INVALID"
+    });
+  }
+
   if (!isPlainObject(value)) {
     throw createActionRuntimeError(500, `Action definition ${fieldName} must be a json-rest-schema schema definition.`, {
       code: "ACTION_DEFINITION_INVALID"
@@ -105,52 +98,6 @@ function normalizeSingleActionSchema(value, fieldName, { required = false, defau
   }
 }
 
-function normalizeActionInputDefinition(value, fieldName, { required = false } = {}) {
-  if (value == null) {
-    if (!required) {
-      return null;
-    }
-
-    throw createActionRuntimeError(500, `Action definition ${fieldName} is required.`, {
-      code: "ACTION_DEFINITION_INVALID"
-    });
-  }
-
-  if (Array.isArray(value)) {
-    throw createActionRuntimeError(500, `Action definition ${fieldName} must be a single schema definition.`, {
-      code: "ACTION_DEFINITION_INVALID"
-    });
-  }
-
-  return normalizeSingleActionSchema(value, fieldName, {
-    required,
-    defaultMode: "patch"
-  });
-}
-
-function normalizeActionOutputDefinition(value, fieldName, { required = false } = {}) {
-  if (value == null) {
-    if (!required) {
-      return null;
-    }
-
-    throw createActionRuntimeError(500, `Action definition ${fieldName} is required.`, {
-      code: "ACTION_DEFINITION_INVALID"
-    });
-  }
-
-  if (Array.isArray(value)) {
-    throw createActionRuntimeError(500, `Action definition ${fieldName} must be a single schema definition.`, {
-      code: "ACTION_DEFINITION_INVALID"
-    });
-  }
-
-  return normalizeSingleActionSchema(value, fieldName, {
-    required,
-    defaultMode: "replace"
-  });
-}
-
 function normalizeActionPermission(permission, actionId) {
   if (permission == null) {
     return Object.freeze({
@@ -190,42 +137,6 @@ function normalizeActionPermission(permission, actionId) {
   });
 }
 
-function normalizeAuditConfig(audit, { actionId }) {
-  const source = audit && typeof audit === "object" ? audit : {};
-  const actionName = normalizeText(source.actionName || actionId);
-  const metadataBuilder = source.metadataBuilder;
-  const piiTags = normalizeStringArray(source.piiTags, {
-    fieldName: "audit.piiTags",
-    allowEmpty: true
-  });
-
-  if (metadataBuilder != null && typeof metadataBuilder !== "function") {
-    throw createActionRuntimeError(500, "Action definition audit.metadataBuilder must be a function when provided.", {
-      code: "ACTION_DEFINITION_INVALID"
-    });
-  }
-
-  return Object.freeze({
-    actionName,
-    metadataBuilder: typeof metadataBuilder === "function" ? metadataBuilder : null,
-    piiTags
-  });
-}
-
-function normalizeObservabilityConfig(observability) {
-  const source = observability && typeof observability === "object" ? observability : {};
-  const metricTags = normalizeStringArray(source.metricTags, {
-    fieldName: "observability.metricTags",
-    allowEmpty: true
-  });
-  const sampleRate = Number(source.sampleRate);
-
-  return Object.freeze({
-    metricTags,
-    sampleRate: Number.isFinite(sampleRate) && sampleRate >= 0 && sampleRate <= 1 ? sampleRate : null
-  });
-}
-
 function normalizeActionExtensions(value) {
   if (value == null) {
     return Object.freeze({});
@@ -286,13 +197,8 @@ function normalizeActionDefinition(definition, { contributorId = "", contributor
     });
   }
 
-  const channels = normalizeStringArray(source.channels, {
-    fieldName: "channels"
-  });
-
-  const surfaces = normalizeStringArray(source.surfaces, {
-    fieldName: "surfaces"
-  });
+  const channels = normalizeStringArray(source.channels, "channels");
+  const surfaces = normalizeStringArray(source.surfaces, "surfaces");
 
   const idempotency = normalizeText(source.idempotency || "none").toLowerCase();
   if (!ACTION_IDEMPOTENCY_SET.has(idempotency)) {
@@ -318,18 +224,15 @@ function normalizeActionDefinition(definition, { contributorId = "", contributor
     kind,
     channels,
     surfaces,
-    input: normalizeActionInputDefinition(source.input, "input", {
-      required: true
+    input: normalizeActionSchema(source.input, "input", {
+      required: true,
+      defaultMode: "patch"
     }),
-    output: normalizeActionOutputDefinition(source.output, "output", {
-      required: false
+    output: normalizeActionSchema(source.output, "output", {
+      defaultMode: "replace"
     }),
     idempotency,
     permission: normalizeActionPermission(source.permission, id),
-    audit: normalizeAuditConfig(source.audit, {
-      actionId: id
-    }),
-    observability: normalizeObservabilityConfig(source.observability),
     extensions: normalizeActionExtensions(source.extensions),
     events: normalizeActionEvents(source.events, id),
     execute: source.execute,
@@ -371,15 +274,7 @@ function createActionVersionKey(actionId, version) {
 }
 
 const __testables = {
-  normalizeText,
-  isPlainObject,
-  normalizeStringArray,
-  normalizeSingleActionSchema,
-  normalizeActionInputDefinition,
-  normalizeActionOutputDefinition,
-  normalizeActionPermission,
-  normalizeAuditConfig,
-  normalizeObservabilityConfig,
+  normalizeActionSchema,
   normalizeActionExtensions
 };
 
@@ -388,8 +283,6 @@ export {
   createActionRuntimeError,
   normalizeActionDefinition,
   normalizeActionContributor,
-  normalizeActionDomain,
   createActionVersionKey,
-  isPlainObject,
   __testables
 };

package/{shared → server}/actions/actionDefinitions.test.js

@@ -56,34 +56,34 @@ function createPatchSchema() {
   };
 }
 
-test("normalizeActionInputDefinition accepts a single schema definition", () => {
-  const definition = __testables.normalizeActionInputDefinition(
+test("normalizeActionSchema accepts a single schema definition", () => {
+  const definition = __testables.normalizeActionSchema(
     createPatchSchema(),
     "input",
-    { required: true }
+    { required: true, defaultMode: "patch" }
   );
 
   assertJsonRestSchemaDefinition(definition);
 });
 
-test("normalizeActionInputDefinition rejects section-map syntax", () => {
+test("normalizeActionSchema rejects section-map syntax", () => {
   assert.throws(
     () =>
-      __testables.normalizeActionInputDefinition(
+      __testables.normalizeActionSchema(
         {
           payload: createPatchSchema()
         },
         "input",
-        { required: true }
+        { required: true, defaultMode: "patch" }
       ),
     /Action definition input must be a schema definition object/
   );
 });
 
-test("normalizeActionInputDefinition rejects bare schema instances", () => {
+test("normalizeActionSchema rejects bare schema instances", () => {
   assert.throws(
     () =>
-      __testables.normalizeActionInputDefinition(
+      __testables.normalizeActionSchema(
         createSchema({
           name: {
             type: "string",
@@ -91,22 +91,22 @@ test("normalizeActionInputDefinition rejects bare schema instances", () => {
           }
         }),
         "input",
-        { required: true }
+        { required: true, defaultMode: "patch" }
       ),
     /Action definition input must be a schema definition object/
   );
 });
 
-test("normalizeActionInputDefinition rejects validator arrays", () => {
+test("normalizeActionSchema rejects validator arrays", () => {
   assert.throws(
     () =>
-      __testables.normalizeActionInputDefinition(
+      __testables.normalizeActionSchema(
         [
           createWorkspaceSlugSchema(),
           createPatchSchema()
         ],
         "input",
-        { required: true }
+        { required: true, defaultMode: "patch" }
       ),
     /input must be a single schema definition/
   );
@@ -148,8 +148,8 @@ test("normalizeActionDefinition stays channel-agnostic and ignores unknown extra
   assert.equal(Object.prototype.hasOwnProperty.call(definition, "customExtension"), false);
 });
 
-test("normalizeActionOutputDefinition accepts single schema definitions", () => {
-  const output = __testables.normalizeActionOutputDefinition(
+test("normalizeActionSchema accepts single schema definitions", () => {
+  const output = __testables.normalizeActionSchema(
     {
       schema: createSchema({
         ok: {
@@ -159,35 +159,89 @@ test("normalizeActionOutputDefinition accepts single schema definitions", () =>
       })
     },
     "output",
-    { required: false }
+    { defaultMode: "replace" }
   );
 
   assertJsonRestSchemaDefinition(output);
 });
 
-test("normalizeActionOutputDefinition rejects section-map syntax", () => {
+test("normalizeActionSchema rejects section-map syntax", () => {
   assert.throws(
     () =>
-      __testables.normalizeActionOutputDefinition(
+      __testables.normalizeActionSchema(
         {
           payload: createPatchSchema()
         },
         "output",
-        { required: false }
+        { defaultMode: "replace" }
       ),
     /Action definition output must be a schema definition object/
   );
 });
 
-test("normalizeActionInputDefinition preserves mode for json-rest-schema definitions", () => {
-  const definition = __testables.normalizeActionInputDefinition(
+test("normalizeActionSchema preserves mode for json-rest-schema definitions", () => {
+  const definition = __testables.normalizeActionSchema(
     {
       schema: createMockJsonRestSchema(),
       mode: "patch"
     },
     "input",
-    { required: true }
+    { required: true, defaultMode: "patch" }
   );
 
   assert.equal(definition.mode, "patch");
 });
+
+test("normalizeActionSchema rejects a missing required schema and allows a missing optional one", () => {
+  assert.equal(__testables.normalizeActionSchema(null, "output"), null);
+  assert.throws(
+    () => __testables.normalizeActionSchema(undefined, "input", { required: true }),
+    /Action definition input is required/
+  );
+});
+
+test("normalizeActionDefinition keeps only the contract the runtime enforces", () => {
+  const definition = normalizeActionDefinition({
+    id: "demo.status.read",
+    domain: "demo",
+    channels: ["api"],
+    surfaces: ["app"],
+    input: { schema: createSchema({}) },
+    audit: { actionName: "demo.status.read" },
+    observability: {},
+    execute: async () => ({})
+  });
+
+  assert.equal(Object.hasOwn(definition, "audit"), false);
+  assert.equal(Object.hasOwn(definition, "observability"), false);
+  assert.deepEqual(Object.keys(definition).sort(), [
+    "channels",
+    "contributorId",
+    "domain",
+    "events",
+    "execute",
+    "extensions",
+    "id",
+    "idempotency",
+    "input",
+    "kind",
+    "output",
+    "permission",
+    "surfaces",
+    "version"
+  ]);
+});
+
+test("normalizeActionDefinition validates domains with the architecture id pattern", () => {
+  const base = {
+    id: "demo.status.read",
+    channels: ["api"],
+    surfaces: ["app"],
+    input: { schema: createSchema({}) },
+    execute: async () => ({})
+  };
+  assert.equal(normalizeActionDefinition({ ...base, domain: " Demo.Status " }).domain, "demo.status");
+  assert.throws(() => normalizeActionDefinition({ ...base, domain: "1demo" }), {
+    code: "ACTION_DEFINITION_INVALID"
+  });
+});