@jskit-ai/kernel 0.1.158 → 0.1.160

package/server/platform/installedRuntime.test.js

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createInstalledRuntime } from "@jskit-ai/kernel/server/platform";
+
+test("installed runtime composes explicit package providers and application inputs", async (context) => {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "jskit-installed-runtime-"));
+  context.after(() => rm(appRoot, { recursive: true, force: true }));
+  const packageRoot = path.join(appRoot, "packages", "example");
+  await mkdir(path.join(packageRoot, "src"), { recursive: true });
+  await writeFile(
+    path.join(appRoot, "package.json"),
+    JSON.stringify({
+      name: "fixture-app",
+      private: true,
+      dependencies: { "@fixture/example": "file:packages/example" }
+    })
+  );
+  await writeFile(
+    path.join(packageRoot, "package.json"),
+    JSON.stringify({
+      name: "@fixture/example",
+      version: "0.1.0",
+      type: "module",
+      jskit: {
+        kind: "runtime",
+        capabilities: {
+          requires: ["runtime.env"],
+          provides: ["feature.example"]
+        },
+        runtime: {
+          server: {
+            providers: [{ entrypoint: "src/provider.js", export: "ExampleProvider" }]
+          }
+        }
+      }
+    })
+  );
+  await writeFile(
+    path.join(packageRoot, "src", "provider.js"),
+    [
+      "export const ExampleProvider = {",
+      "  id: 'feature.example',",
+      "  requires: { env: 'runtime.env' },",
+      "  provides: { example: 'feature.example' },",
+      "  setup({ env }) { return { example: { name: env.APP_NAME } }; }",
+      "};"
+    ].join("\n")
+  );
+
+  let observed = null;
+  const observer = defineProvider({
+    id: "fixture.observer",
+    requires: {
+      actions: "runtime.actions",
+      example: "feature.example",
+      logger: "runtime.logger"
+    },
+    setup(dependencies) {
+      observed = dependencies;
+    }
+  });
+  const runtime = await createInstalledRuntime({
+    appRoot,
+    env: { APP_NAME: "Books" },
+    logger: { info() {} },
+    providers: [observer]
+  });
+
+  assert.equal(observed.example.name, "Books");
+  assert.equal(typeof observed.actions.execute, "function");
+  assert.equal(typeof observed.logger.info, "function");
+  assert.deepEqual(runtime.packageOrder, ["@fixture/example"]);
+  assert.deepEqual(runtime.providerPackageOrder, ["@fixture/example"]);
+  assert.deepEqual(runtime.diagnostics.providerOrder, [
+    "feature.example",
+    "runtime.events",
+    "runtime.actions",
+    "fixture.observer"
+  ]);
+  assert.equal(Object.hasOwn(runtime, "app"), false);
+});
+
+test("installed runtime attaches one idempotent Fastify shutdown hook", async (context) => {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "jskit-installed-runtime-close-"));
+  context.after(() => rm(appRoot, { recursive: true, force: true }));
+  await writeFile(path.join(appRoot, "package.json"), JSON.stringify({ name: "fixture-app", private: true }));
+  const hooks = [];
+  const fastify = {
+    addHook(name, handler) {
+      hooks.push({ name, handler });
+    }
+  };
+  const installed = await createInstalledRuntime({ appRoot, fastify });
+  const closeHook = hooks.find((entry) => entry.name === "onClose");
+  assert.ok(closeHook);
+  await closeHook.handler();
+  await closeHook.handler();
+  assert.equal(installed.runtime.diagnostics().lifecycleState, "stopped");
+});

package/server/platform/providerRuntime/capabilityProviderLoader.js

@@ -0,0 +1,100 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { defineProvider } from "../../../shared/capabilities/defineProvider.js";
+import { fileExists, isIdentifier, isInsidePackageRoot } from "./helpers.js";
+
+function declaredProviderEntrypoints(packageEntry) {
+  const runtime = packageEntry?.packageMetadata?.runtime;
+  const server = runtime && typeof runtime === "object" ? runtime.server : null;
+  const entries = Array.isArray(server?.providers) ? server.providers : [];
+
+  return entries.map((value) => {
+    const entry = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    if (entry.discover != null) {
+      throw new Error(
+        `Package ${packageEntry.packageId} runtime.server.providers[] must declare an explicit entrypoint and export.`
+      );
+    }
+    const entrypoint = String(entry.entrypoint || "").trim();
+    const exportName = String(entry.export || "").trim();
+    if (!entrypoint) {
+      throw new Error(`Package ${packageEntry.packageId} runtime.server.providers[] entrypoint is required.`);
+    }
+    if (!isIdentifier(exportName)) {
+      throw new Error(
+        `Package ${packageEntry.packageId} runtime.server.providers[] export is invalid: ${exportName || "<missing>"}`
+      );
+    }
+    return Object.freeze({ entrypoint, exportName });
+  });
+}
+
+function normalizeProviderExports(value, packageId, exportName) {
+  const queue = Array.isArray(value) ? [...value] : [value];
+  const providers = [];
+  while (queue.length > 0) {
+    const candidate = queue.shift();
+    if (Array.isArray(candidate)) {
+      queue.unshift(...candidate);
+      continue;
+    }
+    try {
+      providers.push(defineProvider(candidate));
+    } catch (error) {
+      throw new Error(
+        `Package ${packageId} provider export "${exportName}" must contain provider definitions: ${error.message}`,
+        { cause: error }
+      );
+    }
+  }
+  if (providers.length < 1) {
+    throw new Error(`Package ${packageId} provider export "${exportName}" is empty.`);
+  }
+  return providers;
+}
+
+async function loadCapabilityProviders({ packageEntry } = {}) {
+  const providers = [];
+  for (const declaration of declaredProviderEntrypoints(packageEntry)) {
+    const modulePath = path.resolve(packageEntry.packageRoot, declaration.entrypoint);
+    if (!isInsidePackageRoot(packageEntry.packageRoot, modulePath)) {
+      throw new Error(
+        `Package ${packageEntry.packageId} provider entrypoint escapes package root: ${declaration.entrypoint}`
+      );
+    }
+    if (!(await fileExists(modulePath))) {
+      throw new Error(
+        `Package ${packageEntry.packageId} provider entrypoint not found: ${declaration.entrypoint}`
+      );
+    }
+
+    const namespace = await import(pathToFileURL(modulePath).href);
+    if (!Object.hasOwn(namespace, declaration.exportName)) {
+      throw new Error(
+        `Package ${packageEntry.packageId} provider export "${declaration.exportName}" was not found.`
+      );
+    }
+    providers.push(
+      ...normalizeProviderExports(
+        namespace[declaration.exportName],
+        packageEntry.packageId,
+        declaration.exportName
+      )
+    );
+  }
+  return Object.freeze(providers);
+}
+
+function appendCapabilityProviders({ providers, sourceId, seenProviderIds, orderedProviders }) {
+  for (const provider of providers) {
+    if (seenProviderIds.has(provider.id)) {
+      throw new Error(
+        `Provider id "${provider.id}" is duplicated between ${seenProviderIds.get(provider.id)} and ${sourceId}.`
+      );
+    }
+    seenProviderIds.set(provider.id, sourceId);
+    orderedProviders.push(provider);
+  }
+}
+
+export { appendCapabilityProviders, loadCapabilityProviders };

package/server/platform/providerRuntime/capabilityProviderLoader.test.js

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  appendCapabilityProviders,
+  loadCapabilityProviders
+} from "./capabilityProviderLoader.js";
+
+async function fixturePackage() {
+  const packageRoot = await mkdtemp(path.join(tmpdir(), "jskit-capability-provider-"));
+  await mkdir(path.join(packageRoot, "src"), { recursive: true });
+  return {
+    packageRoot,
+    packageId: "@fixture/example",
+    packageMetadata: {
+      runtime: {
+        server: {
+          providers: [{ entrypoint: "src/provider.js", export: "providers" }]
+        }
+      }
+    }
+  };
+}
+
+test("capability provider loader imports explicit provider definitions", async () => {
+  const packageEntry = await fixturePackage();
+  try {
+    await writeFile(
+      path.join(packageEntry.packageRoot, "src", "provider.js"),
+      [
+        "export const providers = [{",
+        "  id: 'feature.example',",
+        "  provides: { example: 'feature.example' },",
+        "  setup() { return { example: { ready: true } }; }",
+        "}];"
+      ].join("\n"),
+      "utf8"
+    );
+
+    const providers = await loadCapabilityProviders({ packageEntry });
+    assert.deepEqual(providers.map((provider) => provider.id), ["feature.example"]);
+    assert.deepEqual(providers[0].provides, { example: "feature.example" });
+  } finally {
+    await rm(packageEntry.packageRoot, { recursive: true, force: true });
+  }
+});
+
+test("capability provider loader rejects discovery, classes, path escapes, and duplicates", async () => {
+  const packageEntry = await fixturePackage();
+  try {
+    packageEntry.packageMetadata.runtime.server.providers = [{ discover: { dir: "src" } }];
+    await assert.rejects(loadCapabilityProviders({ packageEntry }), /explicit entrypoint and export/u);
+
+    packageEntry.packageMetadata.runtime.server.providers = [{ entrypoint: "src/provider.js", export: "Provider" }];
+    await writeFile(
+      path.join(packageEntry.packageRoot, "src", "provider.js"),
+      "export class Provider { static id = 'old.provider'; register() {} }\n",
+      "utf8"
+    );
+    await assert.rejects(loadCapabilityProviders({ packageEntry }), /must contain provider definitions/u);
+
+    packageEntry.packageMetadata.runtime.server.providers = [{ entrypoint: "../outside.js", export: "provider" }];
+    await assert.rejects(loadCapabilityProviders({ packageEntry }), /escapes package root/u);
+
+    const providers = [{ id: "feature.example" }];
+    assert.throws(
+      () => appendCapabilityProviders({
+        providers,
+        sourceId: "second",
+        seenProviderIds: new Map([["feature.example", "first"]]),
+        orderedProviders: []
+      }),
+      /duplicated between first and second/u
+    );
+  } finally {
+    await rm(packageEntry.packageRoot, { recursive: true, force: true });
+  }
+});

package/server/platform/providerRuntime/packageCatalog.js

@@ -1,7 +1,10 @@
 import { sortStrings } from "../../../shared/support/sorting.js";
 import { discoverInstalledPackages } from "../../../internal/node/installedPackages.js";
 
-const EXCLUSIVE_CAPABILITIES = Object.freeze(["auth.provider"]);
+const EXCLUSIVE_CAPABILITIES = Object.freeze([
+  "auth.service",
+  "runtime.database.driver"
+]);
 
 function normalizeUiRoutePath(pathValue) {
   const rawPath = String(pathValue || "").trim();

package/server/platform/surfaceRuntime.js

@@ -1,4 +1,3 @@
-import { createProviderRuntimeFromApp } from "./providerRuntime.js";
 import { matchesPathPrefix, normalizePathname } from "../../shared/surface/paths.js";
 
 function toRequestPathname(urlValue) {
@@ -129,22 +128,9 @@ function resolveRuntimeProfileFromSurface({
   return "";
 }
 
-async function tryCreateProviderRuntimeFromApp(options = {}) {
-  try {
-    return await createProviderRuntimeFromApp(options);
-  } catch (error) {
-    const message = String(error?.message || "");
-    if (message.includes("Lock file not found:")) {
-      return null;
-    }
-    throw error;
-  }
-}
-
 export {
   toRequestPathname,
   shouldServePathForSurface,
   registerSurfaceRequestConstraint,
-  resolveRuntimeProfileFromSurface,
-  tryCreateProviderRuntimeFromApp
+  resolveRuntimeProfileFromSurface
 };

package/server/runtime/BootstrapProvider.js

@@ -0,0 +1,69 @@
+import { defineProvider } from "../../shared/capabilities/defineProvider.js";
+import { isRecord, normalizeText } from "../../shared/support/normalize.js";
+import { AUTH_POLICY_PUBLIC } from "../../shared/support/policies.js";
+
+function createBootstrapRuntime() {
+  const contributors = [];
+  const contributorIds = new Set();
+  let sealed = false;
+
+  function register({ id, order = 0, contribute } = {}) {
+    if (sealed) throw new Error("Bootstrap registration is closed after the first payload is resolved.");
+    const contributorId = normalizeText(id);
+    if (!contributorId) throw new TypeError("Bootstrap contributor id is required.");
+    if (typeof contribute !== "function") throw new TypeError(`Bootstrap contributor "${contributorId}" requires contribute().`);
+    if (contributorIds.has(contributorId)) throw new Error(`Bootstrap contributor "${contributorId}" is duplicated.`);
+    contributorIds.add(contributorId);
+    contributors.push(Object.freeze({ id: contributorId, order: Number.isFinite(order) ? Number(order) : 0, contribute }));
+    return api;
+  }
+
+  async function resolve(context = {}) {
+    sealed = true;
+    let payload = {};
+    const ordered = contributors
+      .map((entry, index) => ({ entry, index }))
+      .sort((left, right) => left.entry.order - right.entry.order || left.index - right.index)
+      .map(({ entry }) => entry);
+    for (const contributor of ordered) {
+      const contribution = await contributor.contribute(Object.freeze({
+        ...(isRecord(context) ? context : {}),
+        payload: Object.freeze({ ...payload })
+      }));
+      payload = { ...payload, ...(isRecord(contribution) ? contribution : {}) };
+    }
+    return Object.freeze(payload);
+  }
+
+  function diagnostics() {
+    return Object.freeze({
+      sealed,
+      contributorIds: Object.freeze(contributors.map((entry) => entry.id).sort())
+    });
+  }
+
+  const api = Object.freeze({ register, resolve, diagnostics });
+  return api;
+}
+
+const BootstrapProvider = defineProvider({
+  id: "runtime.bootstrap",
+  requires: { http: "runtime.http" },
+  provides: { bootstrap: "runtime.bootstrap" },
+  setup({ http }) {
+    const bootstrap = createBootstrapRuntime();
+    http.router.register("GET", "/api/bootstrap", {
+      auth: AUTH_POLICY_PUBLIC,
+      meta: { tags: ["bootstrap"], summary: "Resolve app bootstrap payload" }
+    }, async (request, reply) => {
+      reply.code(200).send(await bootstrap.resolve({
+        request,
+        reply,
+        query: request.query || {}
+      }));
+    });
+    return { bootstrap };
+  }
+});
+
+export { BootstrapProvider, createBootstrapRuntime };

package/server/runtime/EventProvider.js

@@ -0,0 +1,74 @@
+import { defineProvider } from "../../shared/capabilities/defineProvider.js";
+
+function normalizeListener(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("Event listener must be an object.");
+  }
+  const id = String(value.id || "").trim();
+  if (!id) throw new TypeError("Event listener id is required.");
+  if (typeof value.handle !== "function") {
+    throw new TypeError(`Event listener "${id}" requires handle().`);
+  }
+  if (value.matches != null && typeof value.matches !== "function") {
+    throw new TypeError(`Event listener "${id}" matches must be a function when provided.`);
+  }
+  return Object.freeze({
+    id,
+    handle: value.handle,
+    matches: typeof value.matches === "function" ? value.matches : null
+  });
+}
+
+function normalizeEvent(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("Published event must be an object.");
+  }
+  const type = String(value.type || "").trim();
+  if (!type) throw new TypeError("Published event type is required.");
+  return Object.freeze({ ...value, type });
+}
+
+function createEventRuntime() {
+  const listeners = [];
+  const listenerIds = new Set();
+
+  function register(value) {
+    const listener = normalizeListener(value);
+    if (listenerIds.has(listener.id)) {
+      throw new Error(`Event listener "${listener.id}" is duplicated.`);
+    }
+    listenerIds.add(listener.id);
+    listeners.push(listener);
+    return api;
+  }
+
+  async function publish(value) {
+    const event = normalizeEvent(value);
+    for (const listener of listeners) {
+      if (listener.matches && listener.matches(event) !== true) continue;
+      await listener.handle(event);
+    }
+    return event;
+  }
+
+  function diagnostics() {
+    return Object.freeze({
+      listenerIds: Object.freeze(listeners.map((listener) => listener.id))
+    });
+  }
+
+  const api = Object.freeze({ register, publish, diagnostics });
+  return api;
+}
+
+const EventProvider = defineProvider({
+  id: "runtime.events",
+  provides: {
+    events: "runtime.events"
+  },
+  setup() {
+    return { events: createEventRuntime() };
+  }
+});
+
+export { EventProvider, createEventRuntime };

package/server/runtime/EventProvider.test.js

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createEventRuntime } from "./EventProvider.js";
+
+test("event runtime publishes ephemeral events to explicit listeners in registration order", async () => {
+  const events = createEventRuntime();
+  const calls = [];
+  events.register({
+    id: "first",
+    handle(event) {
+      calls.push(`first:${event.type}`);
+    }
+  });
+  events.register({
+    id: "matching",
+    matches(event) {
+      return event.type === "book.saved";
+    },
+    handle(event) {
+      calls.push(`matching:${event.bookId}`);
+    }
+  });
+
+  await events.publish({ type: "book.saved", bookId: "12" });
+
+  assert.deepEqual(calls, ["first:book.saved", "matching:12"]);
+  assert.deepEqual(events.diagnostics().listenerIds, ["first", "matching"]);
+  assert.throws(
+    () => events.register({ id: "first", handle() {} }),
+    /duplicated/u
+  );
+});

package/server/runtime/entityChangeEvents.js

@@ -1,4 +1,3 @@
-import { isContainerToken } from "../../shared/support/containerToken.js";
 import { normalizeObject, normalizeOpaqueId, normalizeText } from "../../shared/support/normalize.js";
 import { resolveServiceContext } from "./serviceAuthorization.js";
 
@@ -203,7 +202,7 @@ function normalizeRealtimePayload(value, { context = "realtime entity change.pay
 }
 
 function createRealtimeEntityChangeMeta({
-  serviceToken,
+  serviceId,
   methodName,
   event,
   change = {}
@@ -213,7 +212,7 @@ function createRealtimeEntityChangeMeta({
   const meta = {
     ...baseMeta,
     service: Object.freeze({
-      token: serviceToken,
+      id: serviceId,
       method: methodName
     })
   };
@@ -256,7 +255,7 @@ function createRealtimeEntityChangePublisher({
   source,
   entity,
   event,
-  serviceToken,
+  serviceId,
   methodName,
   scopeResolver = resolveDefaultScope
 } = {}) {
@@ -265,8 +264,9 @@ function createRealtimeEntityChangePublisher({
     throw new TypeError("createRealtimeEntityChangePublisher requires event.");
   }
 
-  if (!isContainerToken(serviceToken)) {
-    throw new TypeError("createRealtimeEntityChangePublisher requires a valid serviceToken.");
+  const normalizedServiceId = normalizeText(serviceId);
+  if (!normalizedServiceId) {
+    throw new TypeError("createRealtimeEntityChangePublisher requires serviceId.");
   }
 
   const normalizedMethodName = normalizeText(methodName);
@@ -284,7 +284,7 @@ function createRealtimeEntityChangePublisher({
   return async function publishRealtimeEntityChange(operation, entityId, change = {}, options = {}) {
     const runtimeOptions = resolveRealtimeEntityChangeOptions(change, options);
     const meta = createRealtimeEntityChangeMeta({
-      serviceToken,
+      serviceId: normalizedServiceId,
       methodName: normalizedMethodName,
       event: normalizedEvent,
       change

package/server/runtime/entityChangeEvents.test.js

@@ -224,7 +224,7 @@ test("realtime entity change publisher adds service, semantic, and realtime meta
     source: "vibe64",
     entity: "project",
     event: "vibe64.project.changed",
-    serviceToken: "vibe64.terminals.service",
+    serviceId: "vibe64.terminals",
     methodName: "projectRuntime"
   });
 
@@ -259,7 +259,7 @@ test("realtime entity change publisher adds service, semantic, and realtime meta
     id: "workspace_23"
   });
   assert.equal(payload?.actorId, "user_17");
-  assert.equal(payload?.meta?.service?.token, "vibe64.terminals.service");
+  assert.equal(payload?.meta?.service?.id, "vibe64.terminals");
   assert.equal(payload?.meta?.service?.method, "projectRuntime");
   assert.equal(payload?.meta?.action, "runtime-closed");
   assert.equal(payload?.meta?.reason, "user-request");

package/server/runtime/fastifyBootstrap.js

@@ -1,6 +1,5 @@
 import { ActionRuntimeError } from "../../shared/actions/actionDefinitions.js";
 import { normalizeOpaqueId } from "../../shared/support/normalize.js";
-import { isAppError } from "./errors.js";
 import { resolveDefaultSurfaceId } from "../support/appConfig.js";
 
 const JSON_API_CONTENT_TYPE = "application/vnd.api+json";
@@ -403,44 +402,6 @@ function registerApiErrorHandler(
   });
 }
 
-function ensureApiErrorHandling(
-  app,
-  {
-    fastifyToken = "jskit.fastify",
-    markerToken = "kernel.runtime.apiErrorHandlerRegistered",
-    isAppError: isAppErrorOverride,
-    autoRegister = true,
-    ...handlerOptions
-  } = {}
-) {
-  if (!app || typeof app.make !== "function" || typeof app.has !== "function" || typeof app.instance !== "function") {
-    throw new TypeError("ensureApiErrorHandling requires an application instance.");
-  }
-
-  if (autoRegister === false) {
-    return false;
-  }
-
-  const normalizedMarkerToken = String(markerToken || "").trim() || "kernel.runtime.apiErrorHandlerRegistered";
-  if (app.has(normalizedMarkerToken)) {
-    return false;
-  }
-
-  const fastify = app.make(fastifyToken);
-  if (!fastify || typeof fastify.setErrorHandler !== "function") {
-    throw new TypeError("ensureApiErrorHandling requires a Fastify instance.");
-  }
-
-  const appErrorPredicate = typeof isAppErrorOverride === "function" ? isAppErrorOverride : isAppError;
-  registerApiErrorHandler(fastify, {
-    ...handlerOptions,
-    isAppError: appErrorPredicate
-  });
-  app.instance(normalizedMarkerToken, true);
-
-  return true;
-}
-
 function resolveDatabaseErrorCode(error) {
   const errorCode = String(error?.code || "")
     .trim()
@@ -546,7 +507,6 @@ export {
   registerBodylessContentTypeNormalizer,
   registerRequestLoggingHooks,
   registerApiErrorHandler,
-  ensureApiErrorHandling,
   resolveDatabaseErrorCode,
   recordDbErrorBestEffort,
   runGracefulShutdown

package/server/runtime/index.js

@@ -1,6 +1,5 @@
 export { AppError, createValidationError } from "./errors.js";
 export { parsePositiveInteger } from "./integers.js";
 export { requireAuth } from "./serviceAuthorization.js";
-export { installServiceRegistrationApi, resolveServiceRegistrations } from "../registries/serviceRegistrationRegistry.js";
-export { registerDomainEventListener } from "../registries/domainEventListenerRegistry.js";
-export { registerBootstrapPayloadContributor } from "../registries/bootstrapPayloadContributorRegistry.js";
+export { BootstrapProvider, createBootstrapRuntime } from "./BootstrapProvider.js";
+export { EventProvider, createEventRuntime } from "./EventProvider.js";

package/server/surface/index.js

@@ -16,4 +16,3 @@ export {
   buildVersionedApiPath,
   isVersionedApiPrefixMatch
 } from "../../shared/surface/apiPaths.js";
-export { SurfaceRoutingServiceProvider } from "./SurfaceRoutingServiceProvider.js";

package/shared/actions/actionDefinitions.js

@@ -242,6 +242,25 @@ function normalizeActionExtensions(value) {
   });
 }
 
+function normalizeActionEvents(value, actionId) {
+  if (value == null) return Object.freeze([]);
+  if (!Array.isArray(value)) {
+    throw createActionRuntimeError(500, `Action definition "${actionId}" events must be an array.`, {
+      code: "ACTION_DEFINITION_INVALID"
+    });
+  }
+  return Object.freeze(value.map((builder, index) => {
+    if (typeof builder !== "function") {
+      throw createActionRuntimeError(
+        500,
+        `Action definition "${actionId}" events[${index}] must be a function.`,
+        { code: "ACTION_DEFINITION_INVALID" }
+      );
+    }
+    return builder;
+  }));
+}
+
 function normalizeActionDefinition(definition, { contributorId = "", contributorDomain = "" } = {}) {
   const source = definition && typeof definition === "object" ? definition : {};
 
@@ -312,6 +331,7 @@ function normalizeActionDefinition(definition, { contributorId = "", contributor
     }),
     observability: normalizeObservabilityConfig(source.observability),
     extensions: normalizeActionExtensions(source.extensions),
+    events: normalizeActionEvents(source.events, id),
     execute: source.execute,
     contributorId: normalizeText(contributorId)
   });