@jskit-ai/kernel 0.1.4

package/server/registries/actionSurfaceSourceRegistry.js

@@ -0,0 +1,150 @@
+import { KERNEL_TOKENS } from "../../shared/support/tokens.js";
+import { assertTaggableApp } from "./primitives.js";
+
+const ACTION_SURFACE_SOURCE_REGISTRY_TOKEN = Symbol.for("jskit.runtime.actions.surfaceSourceRegistry");
+const ACTION_SURFACE_SOURCE_NAME_PATTERN = /^[a-z][a-z0-9_.-]*$/;
+
+function normalizeSurfaceIdValue(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+function normalizeSurfaceSourceName(sourceName, { context = "action surface source" } = {}) {
+  const normalizedSourceName = normalizeSurfaceIdValue(sourceName);
+  if (!ACTION_SURFACE_SOURCE_NAME_PATTERN.test(normalizedSourceName)) {
+    throw new Error(`${context} must match ${ACTION_SURFACE_SOURCE_NAME_PATTERN.toString()}.`);
+  }
+
+  return normalizedSourceName;
+}
+
+function resolveSurfaceRuntime(scope) {
+  if (!scope || typeof scope.has !== "function" || typeof scope.make !== "function") {
+    throw new Error("Action definition materialization requires scope.has()/make().");
+  }
+
+  if (!scope.has(KERNEL_TOKENS.SurfaceRuntime)) {
+    throw new Error("Action definition surfacesFrom requires KERNEL_TOKENS.SurfaceRuntime.");
+  }
+
+  return scope.make(KERNEL_TOKENS.SurfaceRuntime);
+}
+
+function resolveEnabledSurfaceIds(surfaceRuntime) {
+  return Array.isArray(surfaceRuntime?.listEnabledSurfaceIds?.()) ? surfaceRuntime.listEnabledSurfaceIds() : [];
+}
+
+function normalizeSurfaceIdList(surfaceIds, { context = "action.surfacesFrom", surfaceRuntime = null } = {}) {
+  const sourceSurfaceIds = Array.isArray(surfaceIds) ? surfaceIds : [];
+  const enabledSurfaceIds = new Set(
+    resolveEnabledSurfaceIds(surfaceRuntime).map((entry) => normalizeSurfaceIdValue(entry)).filter(Boolean)
+  );
+  const seen = new Set();
+  const normalized = [];
+
+  for (const sourceSurfaceId of sourceSurfaceIds) {
+    const normalizedSurfaceId = normalizeSurfaceIdValue(sourceSurfaceId);
+    if (!normalizedSurfaceId || seen.has(normalizedSurfaceId)) {
+      continue;
+    }
+
+    if (!enabledSurfaceIds.has(normalizedSurfaceId)) {
+      throw new Error(`${context} resolved non-enabled surface "${normalizedSurfaceId}".`);
+    }
+
+    seen.add(normalizedSurfaceId);
+    normalized.push(normalizedSurfaceId);
+  }
+
+  return Object.freeze(normalized);
+}
+
+function createActionSurfaceSourceRegistry() {
+  const sourceResolvers = new Map();
+
+  const register = (sourceName, resolver, { allowOverride = false } = {}) => {
+    const normalizedSourceName = normalizeSurfaceSourceName(sourceName);
+    if (typeof resolver !== "function") {
+      throw new Error(`action surface source "${normalizedSourceName}" resolver must be a function.`);
+    }
+    if (!allowOverride && sourceResolvers.has(normalizedSourceName)) {
+      throw new Error(`action surface source "${normalizedSourceName}" is already registered.`);
+    }
+    sourceResolvers.set(normalizedSourceName, resolver);
+  };
+
+  register("enabled", ({ surfaceRuntime }) => resolveEnabledSurfaceIds(surfaceRuntime));
+
+  return Object.freeze({
+    register,
+    resolve(scope, sourceName, { context = "action.surfacesFrom" } = {}) {
+      const normalizedSourceName = normalizeSurfaceSourceName(sourceName, { context });
+      const resolver = sourceResolvers.get(normalizedSourceName);
+      if (typeof resolver !== "function") {
+        throw new Error(
+          `${context} references unknown surface source "${normalizedSourceName}". Register it via app.actionSurfaceSource().`
+        );
+      }
+
+      const surfaceRuntime = resolveSurfaceRuntime(scope);
+      const resolvedSurfaceIds = resolver({
+        scope,
+        sourceName: normalizedSourceName,
+        surfaceRuntime
+      });
+
+      return normalizeSurfaceIdList(resolvedSurfaceIds, {
+        context,
+        surfaceRuntime
+      });
+    }
+  });
+}
+
+function resolveActionSurfaceSourceRegistry(scope) {
+  if (!scope || typeof scope.has !== "function" || typeof scope.make !== "function") {
+    throw new Error("Action surface source resolution requires scope.has()/make().");
+  }
+  if (!scope.has(ACTION_SURFACE_SOURCE_REGISTRY_TOKEN)) {
+    throw new Error("Action surface source registry is not registered.");
+  }
+  return scope.make(ACTION_SURFACE_SOURCE_REGISTRY_TOKEN);
+}
+
+function resolveActionSurfaceSourceIds(scope, sourceName, { context = "action.surfacesFrom" } = {}) {
+  const sourceRegistry = resolveActionSurfaceSourceRegistry(scope);
+  return sourceRegistry.resolve(scope, sourceName, { context });
+}
+
+function installActionSurfaceSourceRegistrationApi(app) {
+  if (typeof app.actionSurfaceSource === "function") {
+    return;
+  }
+
+  const registerActionSurfaceSource = function registerActionSurfaceSource(sourceName, resolver) {
+    const sourceRegistry = resolveActionSurfaceSourceRegistry(this);
+    sourceRegistry.register(sourceName, resolver);
+    return this;
+  };
+
+  Object.defineProperty(app, "actionSurfaceSource", {
+    configurable: true,
+    writable: true,
+    value: registerActionSurfaceSource
+  });
+}
+
+function ensureActionSurfaceSourceRegistry(app) {
+  assertTaggableApp(app, {
+    context: "ensureActionSurfaceSourceRegistry"
+  });
+  if (typeof app.has !== "function") {
+    throw new Error("ensureActionSurfaceSourceRegistry requires app.has().");
+  }
+
+  if (!app.has(ACTION_SURFACE_SOURCE_REGISTRY_TOKEN)) {
+    app.singleton(ACTION_SURFACE_SOURCE_REGISTRY_TOKEN, () => createActionSurfaceSourceRegistry());
+  }
+  installActionSurfaceSourceRegistrationApi(app);
+}
+
+export { ensureActionSurfaceSourceRegistry, resolveActionSurfaceSourceIds };

package/server/registries/bootstrapPayloadContributorRegistry.js

@@ -0,0 +1,41 @@
+import { normalizeObject } from "../../shared/support/normalize.js";
+import { normalizeContributorEntry, registerTaggedSingleton, resolveTaggedEntries } from "./primitives.js";
+
+const BOOTSTRAP_PAYLOAD_CONTRIBUTOR_TAG = Symbol.for("jskit.runtime.bootstrap.payloadContributors");
+
+function registerBootstrapPayloadContributor(app, token, factory) {
+  registerTaggedSingleton(app, token, factory, BOOTSTRAP_PAYLOAD_CONTRIBUTOR_TAG, {
+    context: "registerBootstrapPayloadContributor"
+  });
+}
+
+function resolveBootstrapPayloadContributors(scope) {
+  return resolveTaggedEntries(scope, BOOTSTRAP_PAYLOAD_CONTRIBUTOR_TAG)
+    .map((entry) => normalizeContributorEntry(entry))
+    .filter(Boolean);
+}
+
+async function resolveBootstrapPayload(scope, context = {}) {
+  const contributors = resolveBootstrapPayloadContributors(scope);
+  let payload = {};
+
+  for (const contributor of contributors) {
+    const contribution = await contributor.contribute({
+      ...normalizeObject(context),
+      payload: Object.freeze({ ...payload })
+    });
+    payload = {
+      ...payload,
+      ...normalizeObject(contribution)
+    };
+  }
+
+  return payload;
+}
+
+export {
+  BOOTSTRAP_PAYLOAD_CONTRIBUTOR_TAG,
+  registerBootstrapPayloadContributor,
+  resolveBootstrapPayloadContributors,
+  resolveBootstrapPayload
+};

package/server/registries/domainEventListenerRegistry.js

@@ -0,0 +1,61 @@
+import { normalizeObject } from "../../shared/support/normalize.js";
+import { registerTaggedSingleton, resolveTaggedEntries } from "./primitives.js";
+
+const DOMAIN_EVENT_LISTENER_TAG = Symbol.for("jskit.runtime.domainEvent.listeners");
+
+function normalizeDomainEventListener(entry) {
+  if (typeof entry === "function") {
+    return {
+      listenerId: String(entry.name || "anonymous"),
+      matches: null,
+      handle: entry
+    };
+  }
+
+  if (entry && typeof entry === "object" && typeof entry.handle === "function") {
+    return {
+      ...entry,
+      listenerId: String(entry.listenerId || "anonymous"),
+      matches: typeof entry.matches === "function" ? entry.matches : null
+    };
+  }
+
+  return null;
+}
+
+function registerDomainEventListener(app, token, factory) {
+  registerTaggedSingleton(app, token, factory, DOMAIN_EVENT_LISTENER_TAG, {
+    context: "registerDomainEventListener"
+  });
+}
+
+function resolveDomainEventListeners(scope) {
+  return resolveTaggedEntries(scope, DOMAIN_EVENT_LISTENER_TAG)
+    .map((entry) => normalizeDomainEventListener(entry))
+    .filter(Boolean);
+}
+
+function createDomainEvents(scope) {
+  return Object.freeze({
+    async publish(event = {}) {
+      const payload = normalizeObject(event);
+      const listeners = resolveDomainEventListeners(scope);
+
+      for (const listener of listeners) {
+        if (listener.matches && listener.matches(payload) !== true) {
+          continue;
+        }
+        await listener.handle(payload);
+      }
+
+      return null;
+    }
+  });
+}
+
+export {
+  DOMAIN_EVENT_LISTENER_TAG,
+  registerDomainEventListener,
+  resolveDomainEventListeners,
+  createDomainEvents
+};

package/server/registries/index.js

@@ -0,0 +1,36 @@
+export {
+  BOOTSTRAP_PAYLOAD_CONTRIBUTOR_TAG,
+  registerBootstrapPayloadContributor,
+  resolveBootstrapPayloadContributors,
+  resolveBootstrapPayload
+} from "./bootstrapPayloadContributorRegistry.js";
+export {
+  DOMAIN_EVENT_LISTENER_TAG,
+  registerDomainEventListener,
+  resolveDomainEventListeners,
+  createDomainEvents
+} from "./domainEventListenerRegistry.js";
+export {
+  SERVICE_REGISTRATION_TAG,
+  normalizeServiceRegistration,
+  materializeServiceRegistration,
+  registerServiceRegistration,
+  resolveServiceRegistrations,
+  installServiceRegistrationApi
+} from "./serviceRegistrationRegistry.js";
+export {
+  ROUTE_VISIBILITY_RESOLVER_TAG,
+  resolveRouteVisibilityResolvers,
+  registerRouteVisibilityResolver,
+  resolveRouteVisibilityContext
+} from "./routeVisibilityResolverRegistry.js";
+export {
+  ensureActionSurfaceSourceRegistry,
+  resolveActionSurfaceSourceIds
+} from "./actionSurfaceSourceRegistry.js";
+export {
+  normalizeNestedEntries,
+  assertTaggableApp,
+  registerTaggedSingleton,
+  resolveTaggedEntries
+} from "./primitives.js";

package/server/registries/primitives.js

@@ -0,0 +1,63 @@
+function normalizeNestedEntries(value) {
+  const queue = Array.isArray(value) ? [...value] : [value];
+  const entries = [];
+
+  while (queue.length > 0) {
+    const entry = queue.shift();
+    if (Array.isArray(entry)) {
+      queue.push(...entry);
+      continue;
+    }
+    if (entry == null) {
+      continue;
+    }
+    entries.push(entry);
+  }
+
+  return entries;
+}
+
+function assertTaggableApp(app, { context = "registry", ErrorType = Error } = {}) {
+  if (!app || typeof app.singleton !== "function" || typeof app.tag !== "function") {
+    throw new ErrorType(`${context} requires application singleton()/tag().`);
+  }
+}
+
+function registerTaggedSingleton(app, token, factory, tag, { context = "registry", ErrorType = Error } = {}) {
+  assertTaggableApp(app, { context, ErrorType });
+  app.singleton(token, factory);
+  app.tag(token, tag);
+}
+
+function resolveTaggedEntries(scope, tag) {
+  if (!scope || typeof scope.resolveTag !== "function") {
+    return [];
+  }
+  return normalizeNestedEntries(scope.resolveTag(tag));
+}
+
+function normalizeContributorEntry(entry) {
+  if (typeof entry === "function") {
+    return {
+      contributorId: String(entry.name || "anonymous"),
+      contribute: entry
+    };
+  }
+
+  if (entry && typeof entry === "object" && typeof entry.contribute === "function") {
+    return {
+      ...entry,
+      contributorId: String(entry.contributorId || "anonymous")
+    };
+  }
+
+  return null;
+}
+
+export {
+  normalizeNestedEntries,
+  assertTaggableApp,
+  registerTaggedSingleton,
+  resolveTaggedEntries,
+  normalizeContributorEntry
+};

package/server/registries/routeVisibilityResolverRegistry.js

@@ -0,0 +1,87 @@
+import { normalizeRouteVisibility, normalizeRouteVisibilityToken, normalizeVisibilityContext } from "../../shared/support/visibility.js";
+import { normalizeText } from "../../shared/support/normalize.js";
+import { ROUTE_VISIBILITY_PUBLIC } from "../../shared/support/policies.js";
+import { RouteRegistrationError } from "../http/lib/errors.js";
+import { registerTaggedSingleton, resolveTaggedEntries } from "./primitives.js";
+
+const ROUTE_VISIBILITY_RESOLVER_TAG = Symbol.for("jskit.runtime.http.visibilityResolvers");
+
+function normalizeRouteVisibilityResolver(entry) {
+  if (typeof entry === "function") {
+    return {
+      resolverId: normalizeText(entry.name) || "anonymous",
+      resolve: entry
+    };
+  }
+
+  if (!entry || typeof entry !== "object" || Array.isArray(entry) || typeof entry.resolve !== "function") {
+    return null;
+  }
+
+  return {
+    resolverId: normalizeText(entry.resolverId) || "anonymous",
+    resolve: entry.resolve
+  };
+}
+
+function resolveRouteVisibilityResolvers(scope) {
+  return resolveTaggedEntries(scope, ROUTE_VISIBILITY_RESOLVER_TAG)
+    .map((entry) => normalizeRouteVisibilityResolver(entry))
+    .filter(Boolean);
+}
+
+function registerRouteVisibilityResolver(app, token, factory) {
+  registerTaggedSingleton(app, token, factory, ROUTE_VISIBILITY_RESOLVER_TAG, {
+    context: "registerRouteVisibilityResolver",
+    ErrorType: RouteRegistrationError
+  });
+}
+
+async function resolveRouteVisibilityContext({
+  resolutionScope = null,
+  request = null,
+  routeVisibility = ROUTE_VISIBILITY_PUBLIC,
+  context = {},
+  input = {},
+  deps = {},
+  actionId = "",
+  version = null,
+  channel = "api"
+} = {}) {
+  const normalizedRouteVisibility = normalizeRouteVisibilityToken(routeVisibility);
+  const normalizedCoreVisibility = normalizeRouteVisibility(normalizedRouteVisibility);
+  const resolvers = resolveRouteVisibilityResolvers(resolutionScope);
+  const patch = {};
+
+  for (const resolver of resolvers) {
+    const contribution = await resolver.resolve({
+      request,
+      visibility: normalizedRouteVisibility,
+      context,
+      input,
+      deps,
+      actionId: normalizeText(actionId),
+      version: version == null ? null : version,
+      channel: normalizeText(channel).toLowerCase() || "api"
+    });
+
+    if (!contribution || typeof contribution !== "object" || Array.isArray(contribution)) {
+      continue;
+    }
+
+    Object.assign(patch, contribution);
+  }
+
+  return normalizeVisibilityContext({
+    ...patch,
+    visibility: normalizedRouteVisibility,
+    requiresActorScope: patch.requiresActorScope === true || normalizedCoreVisibility === "user"
+  });
+}
+
+export {
+  ROUTE_VISIBILITY_RESOLVER_TAG,
+  resolveRouteVisibilityResolvers,
+  registerRouteVisibilityResolver,
+  resolveRouteVisibilityContext
+};