@jskit-ai/kernel 0.1.4

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@jskit-ai/kernel",
+  "version": "0.1.4",
+  "type": "module",
+  "dependencies": {
+    "typebox": "^1.0.81"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    "./_testable": "./_testable/index.js",
+    "./client": {
+      "types": "./client/index.d.ts",
+      "default": "./client/index.js"
+    },
+    "./client/moduleBootstrap": "./client/moduleBootstrap.js",
+    "./client/vite": "./client/vite/index.js",
+    "./server/actions": "./server/actions/index.js",
+    "./server/http": "./server/http/index.js",
+    "./server/platform": "./server/platform/index.js",
+    "./server/runtime": "./server/runtime/index.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/actions": "./shared/actions/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",
+    "./shared/support/tokens": "./shared/support/tokens.js",
+    "./shared/support/normalize": "./shared/support/normalize.js",
+    "./shared/support/returnToPath": "./shared/support/returnToPath.js",
+    "./shared/support/visibility": "./shared/support/visibility.js",
+    "./shared/support/linkPath": "./shared/support/linkPath.js",
+    "./shared/surface": "./shared/surface/index.js",
+    "./shared/surface/paths": "./shared/surface/paths.js",
+    "./shared/surface/runtime": "./shared/surface/runtime.js",
+    "./shared/surface/registry": "./shared/surface/registry.js"
+  }
+}

package/server/actions/ActionRuntimeServiceProvider.js

@@ -0,0 +1,309 @@
+import { normalizeActionDomain } from "../../shared/actions/actionDefinitions.js";
+import { createNoopAuditAdapter } from "../../shared/actions/audit.js";
+import { createNoopIdempotencyAdapter } from "../../shared/actions/idempotency.js";
+import { createNoopObservabilityAdapter } from "../../shared/actions/observability.js";
+import { createActionRegistry } from "../../shared/actions/registry.js";
+import { createSurfaceRuntime } from "../../shared/surface/runtime.js";
+import { normalizeObject } from "../../shared/support/normalize.js";
+import { KERNEL_TOKENS, isContainerToken } from "../../shared/support/tokens.js";
+import { installServiceRegistrationApi } from "../registries/serviceRegistrationRegistry.js";
+import {
+  ensureActionSurfaceSourceRegistry,
+  resolveActionSurfaceSourceIds
+} from "../registries/actionSurfaceSourceRegistry.js";
+import {
+  normalizeContributorEntry,
+  normalizeNestedEntries,
+  registerTaggedSingleton,
+  resolveTaggedEntries as resolveRegistryTaggedEntries
+} from "../registries/primitives.js";
+
+const ACTION_RUNTIME_API = Object.freeze({
+  createActionRegistry,
+  createNoopIdempotencyAdapter,
+  createNoopAuditAdapter,
+  createNoopObservabilityAdapter
+});
+const ACTION_RUNTIME_CONTRIBUTOR_TAG = Symbol.for("jskit.runtime.actions.contributors");
+const ACTION_CONTEXT_CONTRIBUTOR_TAG = Symbol.for("jskit.runtime.actions.contextContributors");
+const LOGGER_TOKEN = Symbol.for("jskit.logger");
+let ACTION_RUNTIME_CONTRIBUTOR_INDEX = 0;
+
+function createSurfaceRuntimeFromAppConfig(scope) {
+  if (!scope || typeof scope.has !== "function" || typeof scope.make !== "function") {
+    throw new Error("Surface runtime registration requires scope.has()/make().");
+  }
+
+  if (!scope.has("appConfig")) {
+    throw new Error(
+      "ActionRuntimeServiceProvider requires appConfig.surfaceDefinitions when KERNEL_TOKENS.SurfaceRuntime is not registered."
+    );
+  }
+
+  const appConfig = normalizeObject(scope.make("appConfig"));
+  const surfaceDefinitions = normalizeObject(appConfig.surfaceDefinitions);
+  if (Object.keys(surfaceDefinitions).length < 1) {
+    throw new Error(
+      "ActionRuntimeServiceProvider requires appConfig.surfaceDefinitions when KERNEL_TOKENS.SurfaceRuntime is not registered."
+    );
+  }
+
+  return createSurfaceRuntime({
+    allMode: appConfig.surfaceModeAll,
+    surfaces: surfaceDefinitions,
+    defaultSurfaceId: appConfig.surfaceDefaultId
+  });
+}
+
+function normalizeDependencyMap(value, { context = "action dependencies" } = {}) {
+  const source = normalizeObject(value);
+  const normalized = {};
+
+  for (const [key, token] of Object.entries(source)) {
+    const dependencyName = String(key || "").trim();
+    if (!dependencyName) {
+      throw new Error(`${context} keys must be non-empty strings.`);
+    }
+    if (!isContainerToken(token)) {
+      throw new Error(`${context}.${dependencyName} must be a valid container token.`);
+    }
+    normalized[dependencyName] = token;
+  }
+
+  return Object.freeze(normalized);
+}
+
+function resolveActionContributors(scope) {
+  return resolveRegistryTaggedEntries(scope, ACTION_RUNTIME_CONTRIBUTOR_TAG).filter(
+    (entry) => entry && typeof entry === "object" && !Array.isArray(entry)
+  );
+}
+
+function resolveActionContextContributors(scope) {
+  return resolveRegistryTaggedEntries(scope, ACTION_CONTEXT_CONTRIBUTOR_TAG)
+    .map((entry) => normalizeContributorEntry(entry))
+    .filter(Boolean);
+}
+
+function createActionExecutor(actionRegistry) {
+  return Object.freeze({
+    execute(payload) {
+      const source = normalizeObject(payload);
+      return actionRegistry.execute({
+        actionId: source.actionId,
+        version: source.version == null ? null : source.version,
+        input: normalizeObject(source.input),
+        context: normalizeObject(source.context),
+        deps: normalizeObject(source.deps)
+      });
+    },
+    executeStream(payload) {
+      const source = normalizeObject(payload);
+      return actionRegistry.executeStream({
+        actionId: source.actionId,
+        version: source.version == null ? null : source.version,
+        input: normalizeObject(source.input),
+        context: normalizeObject(source.context),
+        deps: normalizeObject(source.deps)
+      });
+    },
+    listDefinitions() {
+      return actionRegistry.listDefinitions();
+    },
+    getDefinition(actionId, version = null) {
+      return actionRegistry.getDefinition(actionId, version);
+    }
+  });
+}
+
+function createActionContributorToken() {
+  ACTION_RUNTIME_CONTRIBUTOR_INDEX += 1;
+  return Symbol(`jskit.runtime.actions.contributor.${ACTION_RUNTIME_CONTRIBUTOR_INDEX}`);
+}
+
+function materializeDependencies(scope, dependencyMap, { context = "action.dependencies" } = {}) {
+  const normalizedMap = normalizeDependencyMap(dependencyMap, { context });
+  const resolved = {};
+  for (const [name, token] of Object.entries(normalizedMap)) {
+    resolved[name] = scope.make(token);
+  }
+  return Object.freeze(resolved);
+}
+
+function materializeAction(scope, actionDefinition) {
+  const source = normalizeObject(actionDefinition);
+  const materialized = { ...source };
+  const actionDependencies = materializeDependencies(scope, source.dependencies, {
+    context: `action ${String(source.id || "<unknown>")}.dependencies`
+  });
+  const resolvedDependencies = actionDependencies;
+
+  if (Object.hasOwn(source, "surfaces") && Object.hasOwn(source, "surfacesFrom")) {
+    throw new Error(`Action ${String(source.id || "<unknown>")} cannot define both surfaces and surfacesFrom.`);
+  }
+
+  delete materialized.dependencies;
+  delete materialized.surfacesFrom;
+
+  if (Object.hasOwn(source, "surfacesFrom")) {
+    const resolvedSurfaces = resolveActionSurfaceSourceIds(scope, source.surfacesFrom, {
+      context: `action ${String(source.id || "<unknown>")}.surfacesFrom`
+    });
+    if (resolvedSurfaces.length < 1) {
+      return null;
+    }
+    materialized.surfaces = resolvedSurfaces;
+  }
+
+  if (typeof source.execute === "function") {
+    materialized.execute = async function executeMaterializedAction(input, context, runtimeDependencies = {}) {
+      const runtimeDeps = normalizeObject(runtimeDependencies);
+      const mergedDependencies = Object.freeze({
+        ...resolvedDependencies,
+        ...runtimeDeps
+      });
+
+      return source.execute(input, context, mergedDependencies);
+    };
+  }
+
+  return Object.freeze(materialized);
+}
+
+function registerActionDefinition(app, actionSpec, { context = "app.action" } = {}) {
+  const token = createActionContributorToken();
+  registerTaggedSingleton(
+    app,
+    token,
+    (scope) => {
+      const action = materializeAction(scope, actionSpec.action);
+      if (!action) {
+        return null;
+      }
+
+      return {
+        contributorId: actionSpec.contributorId,
+        domain: action.domain,
+        actions: Object.freeze([action])
+      };
+    },
+    ACTION_RUNTIME_CONTRIBUTOR_TAG,
+    { context }
+  );
+}
+
+function normalizeSingleActionRegistration(actionDefinition, { context = "app.action" } = {}) {
+  const source = normalizeObject(actionDefinition);
+  const actionId = String(source.id || "").trim();
+  const contributorId = String(source.contributorId || "").trim() || (actionId ? `action.${actionId}` : "");
+  if (!contributorId) {
+    throw new Error(`${context} requires action.id or action.contributorId.`);
+  }
+
+  const normalizedAction = {
+    ...source
+  };
+  delete normalizedAction.contributorId;
+  normalizedAction.domain = normalizeActionDomain(normalizedAction.domain, {
+    context: `${context} domain`
+  });
+
+  return Object.freeze({
+    contributorId,
+    action: Object.freeze(normalizedAction)
+  });
+}
+
+function installActionRegistrationApi(app) {
+  if (typeof app.action === "function" && typeof app.actions === "function") {
+    return;
+  }
+
+  const registerActions = function registerActions(actionDefinitions = []) {
+    if (!Array.isArray(actionDefinitions)) {
+      throw new Error("app.actions requires an array of action definitions.");
+    }
+
+    const entries = normalizeNestedEntries(actionDefinitions);
+    for (const entry of entries) {
+      this.action(entry);
+    }
+    return this;
+  };
+
+  const registerAction = function registerAction(actionDefinition = {}) {
+    const actionSpec = normalizeSingleActionRegistration(actionDefinition, {
+      context: "app.action"
+    });
+    registerActionDefinition(this, actionSpec, { context: "app.action" });
+    return this;
+  };
+
+  Object.defineProperty(app, "actions", {
+    configurable: true,
+    writable: true,
+    value: registerActions
+  });
+  Object.defineProperty(app, "action", {
+    configurable: true,
+    writable: true,
+    value: registerAction
+  });
+}
+
+function registerActionContextContributor(app, token, factory) {
+  registerTaggedSingleton(
+    app,
+    token,
+    factory,
+    ACTION_CONTEXT_CONTRIBUTOR_TAG,
+    { context: "registerActionContextContributor" }
+  );
+}
+
+class ActionRuntimeServiceProvider {
+  static id = "runtime.actions";
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function" || typeof app.has !== "function" || typeof app.tag !== "function") {
+      throw new Error("ActionRuntimeServiceProvider requires application singleton()/has()/tag().");
+    }
+
+    installActionRegistrationApi(app);
+    ensureActionSurfaceSourceRegistry(app);
+    installServiceRegistrationApi(app);
+
+    if (!app.has(KERNEL_TOKENS.SurfaceRuntime)) {
+      app.singleton(KERNEL_TOKENS.SurfaceRuntime, (scope) => createSurfaceRuntimeFromAppConfig(scope));
+    }
+
+    app.singleton("runtime.actions", () => ACTION_RUNTIME_API);
+
+    if (!app.has("actionRegistry")) {
+      app.singleton("actionRegistry", (scope) => {
+        return createActionRegistry({
+          contributors: resolveActionContributors(scope),
+          idempotencyAdapter: createNoopIdempotencyAdapter(),
+          auditAdapter: createNoopAuditAdapter(),
+          observabilityAdapter: createNoopObservabilityAdapter(),
+          logger: scope.has(LOGGER_TOKEN) ? scope.make(LOGGER_TOKEN) : console
+        });
+      });
+    }
+
+    if (!app.has("actionExecutor")) {
+      app.singleton("actionExecutor", (scope) => createActionExecutor(scope.make("actionRegistry")));
+    }
+  }
+
+  boot() {}
+}
+
+export {
+  ACTION_RUNTIME_CONTRIBUTOR_TAG,
+  ACTION_CONTEXT_CONTRIBUTOR_TAG,
+  resolveActionContributors,
+  resolveActionContextContributors,
+  registerActionContextContributor,
+  ActionRuntimeServiceProvider
+};