@jskit-ai/kernel 0.1.159 → 0.1.161

package/server/actions/actionCatalogue.js

@@ -0,0 +1,162 @@
+import { createActionRegistry } from "../../shared/actions/registry.js";
+import { isRecord } from "../../shared/support/normalize.js";
+
+function normalizeRegistration(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("Action catalogue registration must be an action contributor object.");
+  }
+
+  return value;
+}
+
+function createActionCatalogue({
+  idempotencyAdapter,
+  auditAdapter,
+  observabilityAdapter,
+  events,
+  logger = null
+} = {}) {
+  const contributors = [];
+  const contextContributors = [];
+  const contextContributorIds = new Set();
+  let registry = createActionRegistry({
+    contributors,
+    idempotencyAdapter,
+    auditAdapter,
+    observabilityAdapter,
+    events,
+    logger
+  });
+  let sealed = false;
+
+  function register(contributor) {
+    if (sealed) {
+      throw new Error("Action catalogue registration is closed after discovery or execution begins.");
+    }
+    const nextContributors = [...contributors, normalizeRegistration(contributor)];
+    const nextRegistry = createActionRegistry({
+      contributors: nextContributors,
+      idempotencyAdapter,
+      auditAdapter,
+      observabilityAdapter,
+      events,
+      logger
+    });
+
+    contributors.push(contributor);
+    registry = nextRegistry;
+    return api;
+  }
+
+  function registerContextContributor({ id, contribute } = {}) {
+    if (sealed) {
+      throw new Error("Action catalogue registration is closed after discovery or execution begins.");
+    }
+    const contributorId = String(id || "").trim();
+    if (!contributorId) {
+      throw new TypeError("Action context contributor id is required.");
+    }
+    if (typeof contribute !== "function") {
+      throw new TypeError(`Action context contributor "${contributorId}" requires contribute().`);
+    }
+    if (contextContributorIds.has(contributorId)) {
+      throw new Error(`Action context contributor "${contributorId}" is duplicated.`);
+    }
+    contextContributorIds.add(contributorId);
+    contextContributors.push(Object.freeze({ id: contributorId, contribute }));
+    return api;
+  }
+
+  function currentRegistry() {
+    sealed = true;
+    return registry;
+  }
+
+  function applyContextDefaults(context, patch) {
+    const next = { ...context };
+    for (const [key, value] of Object.entries(isRecord(patch) ? patch : {})) {
+      if (key === "requestMeta") {
+        next.requestMeta = {
+          ...(isRecord(value) ? value : {}),
+          ...(isRecord(next.requestMeta) ? next.requestMeta : {})
+        };
+      } else if (!Object.hasOwn(next, key)) {
+        next[key] = value;
+      }
+    }
+    return next;
+  }
+
+  async function buildExecutionContext({ actionId, version, input, context }) {
+    const registryInstance = currentRegistry();
+    const definition = registryInstance.getDefinition(actionId, version);
+    let enriched = { ...(isRecord(context) ? context : {}) };
+    for (const contributor of contextContributors) {
+      const patch = await contributor.contribute(Object.freeze({
+        actionId: definition.id,
+        version: definition.version,
+        definition,
+        input: Object.freeze({ ...(isRecord(input) ? input : {}) }),
+        context: Object.freeze({ ...enriched })
+      }));
+      enriched = applyContextDefaults(enriched, patch);
+    }
+    return Object.freeze(enriched);
+  }
+
+  async function execute(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().execute({
+      actionId: source.actionId,
+      version: source.version == null ? null : source.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 listDefinitions() {
+    return currentRegistry().listDefinitions();
+  }
+
+  function getDefinition(actionId, version = null) {
+    return currentRegistry().getDefinition(actionId, version);
+  }
+
+  const api = Object.freeze({
+    register,
+    registerContextContributor,
+    execute,
+    executeStream,
+    listDefinitions,
+    getDefinition
+  });
+  return api;
+}
+
+export { createActionCatalogue };

package/server/actions/actionEvents.js

@@ -0,0 +1,66 @@
+import { resolveDefaultScope } from "../runtime/entityChangeEvents.js";
+import { normalizeObject, normalizeOpaqueId, normalizeText } from "../../shared/support/normalize.js";
+
+const ENTITY_CHANGE_OPERATIONS = new Set(["created", "updated", "deleted"]);
+
+function resolveValue(value, execution) {
+  return typeof value === "function" ? value(execution) : value;
+}
+
+function normalizeRealtime(value, execution) {
+  const source = normalizeObject(value);
+  if (Object.keys(source).length === 0) return null;
+  const event = normalizeText(source.event);
+  if (!event) throw new TypeError("Action entity-change realtime.event is required.");
+  const audience = resolveValue(source.audience ?? "event_scope", execution);
+  const payload = resolveValue(source.payload, execution);
+  if (payload != null && (!payload || typeof payload !== "object" || Array.isArray(payload))) {
+    throw new TypeError("Action entity-change realtime.payload must resolve to an object.");
+  }
+  return Object.freeze({
+    event,
+    audience,
+    ...(payload == null ? {} : { payload: Object.freeze({ ...payload }) })
+  });
+}
+
+function createEntityChangedActionEvent({
+  source,
+  entity,
+  operation,
+  entityId,
+  realtime = null
+} = {}) {
+  const normalizedSource = normalizeText(source);
+  const normalizedEntity = normalizeText(entity);
+  if (!normalizedSource) throw new TypeError("Action entity-change source is required.");
+  if (!normalizedEntity) throw new TypeError("Action entity-change entity is required.");
+
+  return function buildEntityChangedEvent(execution = {}) {
+    const normalizedOperation = normalizeText(resolveValue(operation, execution)).toLowerCase();
+    if (!ENTITY_CHANGE_OPERATIONS.has(normalizedOperation)) {
+      throw new TypeError("Action entity-change operation must resolve to created, updated, or deleted.");
+    }
+    const normalizedEntityId = normalizeOpaqueId(resolveValue(entityId, execution));
+    if (normalizedEntityId == null) return null;
+
+    const context = normalizeObject(execution.context);
+    const requestMeta = normalizeObject(context.requestMeta);
+    const realtimeMeta = normalizeRealtime(realtime, execution);
+    return Object.freeze({
+      type: "entity.changed",
+      source: normalizedSource,
+      entity: normalizedEntity,
+      operation: normalizedOperation,
+      entityId: normalizedEntityId,
+      scope: resolveDefaultScope(normalizeObject(context.visibilityContext), { context }),
+      actorId: normalizeOpaqueId(context?.actor?.id),
+      commandId: normalizeText(requestMeta.commandId || requestMeta.idempotencyKey) || null,
+      sourceClientId: normalizeText(requestMeta.sourceClientId) || null,
+      occurredAt: new Date().toISOString(),
+      ...(realtimeMeta ? { realtime: realtimeMeta } : {})
+    });
+  };
+}
+
+export { createEntityChangedActionEvent };

package/server/actions/actionProvider.js

@@ -0,0 +1,23 @@
+import { defineProvider } from "../../shared/capabilities/defineProvider.js";
+import { createEventRuntime } from "../runtime/EventProvider.js";
+import { createActionCatalogue } from "./actionCatalogue.js";
+
+function createActionProvider(options = {}) {
+  return defineProvider({
+    id: "runtime.actions",
+    optional: {
+      events: "runtime.events"
+    },
+    provides: {
+      actions: "runtime.actions"
+    },
+    setup({ events }) {
+      return { actions: createActionCatalogue({
+        ...options,
+        events: events || createEventRuntime()
+      }) };
+    }
+  });
+}
+
+export { createActionProvider };

package/server/actions/index.js

@@ -1,6 +1,3 @@
-export {
-  resolveActionContributors,
-  resolveActionContextContributors,
-  registerActionContextContributor,
-  ActionRuntimeServiceProvider
-} from "./ActionRuntimeServiceProvider.js";
+export { createActionCatalogue } from "./actionCatalogue.js";
+export { createActionProvider } from "./actionProvider.js";
+export { createEntityChangedActionEvent } from "./actionEvents.js";

package/server/features/defineFeature.js

@@ -0,0 +1,131 @@
+import { isRecord } from "../../shared/support/normalize.js";
+import { defineProvider } from "../../shared/capabilities/defineProvider.js";
+
+function exactOutputNames(value, expectedNames, featureId) {
+  const outputs = value == null ? {} : value;
+  if (!isRecord(outputs)) {
+    throw new TypeError(`Feature "${featureId}" setup() must return its declared capability outputs.`);
+  }
+
+  const actualNames = Object.keys(outputs).sort();
+  const normalizedExpectedNames = [...expectedNames].sort();
+  if (
+    actualNames.length !== normalizedExpectedNames.length ||
+    actualNames.some((name, index) => name !== normalizedExpectedNames[index])
+  ) {
+    throw new TypeError(
+      `Feature "${featureId}" setup() outputs must be exactly: ${normalizedExpectedNames.join(", ") || "<none>"}.`
+    );
+  }
+
+  return Object.freeze({ ...outputs });
+}
+
+function normalizeActionFactory(value, featureId) {
+  if (value == null) {
+    return () => [];
+  }
+  if (typeof value === "function") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return () => value;
+  }
+  throw new TypeError(`Feature "${featureId}" actions must be an array or function.`);
+}
+
+function applyActionDefaults(actions, defaults, featureId) {
+  if (!isRecord(defaults)) {
+    throw new TypeError(`Feature "${featureId}" actionDefaults must be an object.`);
+  }
+  if (Object.hasOwn(defaults, "dependencies")) {
+    throw new TypeError(`Feature "${featureId}" actionDefaults cannot declare container dependencies.`);
+  }
+
+  return actions.map((value) => {
+    if (!isRecord(value)) {
+      throw new TypeError(`Feature "${featureId}" actions must contain action definition objects.`);
+    }
+    if (Object.hasOwn(value, "dependencies")) {
+      throw new TypeError(`Feature "${featureId}" actions cannot declare container dependencies.`);
+    }
+    return Object.freeze({ ...defaults, ...value });
+  });
+}
+
+function withoutActionCatalogue(dependencies) {
+  const { actionCatalogue, ...featureDependencies } = dependencies;
+  return Object.freeze(featureDependencies);
+}
+
+function defineFeature({
+  id,
+  domain = id,
+  requires = {},
+  optional = {},
+  provides = {},
+  setup = () => ({}),
+  actions = [],
+  actionDefaults = {},
+  boot = null,
+  shutdown = null
+} = {}) {
+  if (Object.hasOwn(requires || {}, "actionCatalogue") || Object.hasOwn(optional || {}, "actionCatalogue")) {
+    throw new TypeError("Feature dependencies reserve the local name actionCatalogue.");
+  }
+  if (typeof setup !== "function") {
+    throw new TypeError(`Feature "${String(id || "")}" setup must be a function.`);
+  }
+
+  const actionFactory = normalizeActionFactory(actions, String(id || ""));
+  const expectedOutputNames = Object.keys(provides || {});
+
+  return defineProvider({
+    id,
+    requires: {
+      ...requires,
+      actionCatalogue: "runtime.actions"
+    },
+    optional,
+    provides,
+    async setup(dependencies, context) {
+      const { actionCatalogue } = dependencies;
+      const featureDependencies = withoutActionCatalogue(dependencies);
+      const featureContext = Object.freeze({ ...context, actionCatalogue });
+      const outputs = exactOutputNames(
+        await setup(Object.freeze(featureDependencies), featureContext),
+        expectedOutputNames,
+        String(id || "")
+      );
+      const featureActions = await actionFactory(
+        Object.freeze({
+          ...featureDependencies,
+          ...outputs
+        }),
+        featureContext
+      );
+      if (!Array.isArray(featureActions)) {
+        throw new TypeError(`Feature "${String(id || "")}" actions() must return an array.`);
+      }
+
+      const materializedActions = applyActionDefaults(featureActions, actionDefaults, String(id || ""));
+
+      if (materializedActions.length > 0) {
+        actionCatalogue.register({
+          contributorId: String(id || ""),
+          domain,
+          actions: materializedActions
+        });
+      }
+      return outputs;
+    },
+    boot: typeof boot === "function"
+      ? (dependencies, context) => boot(withoutActionCatalogue(dependencies), context)
+      : boot,
+    shutdown: typeof shutdown === "function"
+      ? (dependencies, context) => shutdown(withoutActionCatalogue(dependencies), context)
+      : shutdown
+  });
+}
+
+export { defineFeature };

package/server/features/defineFeature.test.js

@@ -0,0 +1,238 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createSchema } from "json-rest-schema";
+import {
+  createActionProvider,
+  createEntityChangedActionEvent
+} from "@jskit-ai/kernel/server/actions";
+import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import { EventProvider } from "@jskit-ai/kernel/server/runtime";
+
+function emptyInput() {
+  return { schema: createSchema({}) };
+}
+
+test("features capture only named capabilities and publish actions without container lookup", async () => {
+  let setupActionCatalogue = null;
+  const database = Object.freeze({
+    async listBooks() {
+      return [{ id: 1, title: "Kindred" }];
+    }
+  });
+  const databaseProvider = defineProvider({
+    id: "database.test",
+    provides: { database: "runtime.database" },
+    setup() {
+      return { database };
+    }
+  });
+  const booksFeature = defineFeature({
+    id: "feature.books",
+    domain: "books",
+    requires: { database: "runtime.database" },
+    provides: { books: "feature.books" },
+    actionDefaults: {
+      channels: ["api", "assistant"],
+      surfaces: ["app"]
+    },
+    setup({ database: selectedDatabase }, { actionCatalogue }) {
+      setupActionCatalogue = actionCatalogue;
+      return {
+        books: Object.freeze({
+          list: () => selectedDatabase.listBooks()
+        })
+      };
+    },
+    actions({ books }) {
+      return [{
+        id: "books.list",
+        kind: "query",
+        input: emptyInput(),
+        idempotency: "none",
+        async execute() {
+          return books.list();
+        }
+      }];
+    }
+  });
+
+  let actions = null;
+  const observer = defineProvider({
+    id: "test.observer",
+    requires: { actionCatalogue: "runtime.actions" },
+    setup({ actionCatalogue }) {
+      actions = actionCatalogue;
+    }
+  });
+  const runtime = createCapabilityRuntime({
+    providers: [observer, booksFeature, createActionProvider(), databaseProvider]
+  });
+  await runtime.start();
+
+  assert.deepEqual(actions.listDefinitions().map((entry) => entry.id), ["books.list"]);
+  assert.deepEqual(
+    await actions.execute({
+      actionId: "books.list",
+      context: { channel: "assistant", surface: "app" }
+    }),
+    [{ id: 1, title: "Kindred" }]
+  );
+  assert.equal(Object.hasOwn(actions, "make"), false);
+  assert.equal(Object.hasOwn(actions, "resolve"), false);
+  assert.equal(setupActionCatalogue, actions);
+  assert.throws(
+    () => actions.register({ contributorId: "late", domain: "late", actions: [] }),
+    /registration is closed/u
+  );
+});
+
+test("feature registration rejects duplicate actions and undeclared setup outputs", async () => {
+  const action = {
+    id: "books.read",
+    kind: "query",
+    channels: ["api"],
+    surfaces: ["app"],
+    input: emptyInput(),
+    idempotency: "none",
+    async execute() {
+      return {};
+    }
+  };
+  const first = defineFeature({ id: "feature.first", domain: "books", actions: [action] });
+  const second = defineFeature({ id: "feature.second", domain: "books", actions: [action] });
+  const duplicateRuntime = createCapabilityRuntime({
+    providers: [createActionProvider(), first, second]
+  });
+  await assert.rejects(duplicateRuntime.start(), /duplicated between contributors/u);
+
+  const undeclared = defineFeature({
+    id: "feature.undeclared",
+    setup() {
+      return { surprise: true };
+    }
+  });
+  const invalidRuntime = createCapabilityRuntime({
+    providers: [createActionProvider(), undeclared]
+  });
+  await assert.rejects(invalidRuntime.start(), /outputs must be exactly: <none>/u);
+});
+
+test("action context contributors enrich execution without a request scope container", async () => {
+  let actions;
+  const actionProvider = createActionProvider();
+  const feature = defineFeature({
+    id: "feature.context-proof",
+    domain: "context-proof",
+    actions: [{
+      id: "context-proof.read",
+      kind: "query",
+      channels: ["api"],
+      surfaces: ["app"],
+      input: emptyInput(),
+      idempotency: "none",
+      async execute(_input, context) {
+        return context;
+      }
+    }]
+  });
+  const contributor = defineProvider({
+    id: "test.context-contributor",
+    requires: { actionCatalogue: "runtime.actions" },
+    setup({ actionCatalogue }) {
+      actions = actionCatalogue;
+      actionCatalogue.registerContextContributor({
+        id: "test.actor",
+        contribute({ context }) {
+          return {
+            actorId: context.requestMeta?.request?.actorId || "anonymous",
+            requestMeta: { contributed: true }
+          };
+        }
+      });
+      return {};
+    }
+  });
+  const runtime = createCapabilityRuntime({ providers: [actionProvider, contributor, feature] });
+
+  await runtime.start();
+  const context = await actions.execute({
+    actionId: "context-proof.read",
+    context: {
+      channel: "api",
+      surface: "app",
+      requestMeta: {
+        request: { actorId: "user-1" },
+        callerOwned: true
+      }
+    }
+  });
+
+  assert.equal(context.actorId, "user-1");
+  assert.equal(context.requestMeta.contributed, true);
+  assert.deepEqual(context.requestMeta.request, { actorId: "user-1" });
+  assert.equal(context.requestMeta.callerOwned, true);
+  assert.throws(
+    () => actions.registerContextContributor({ id: "late", contribute() {} }),
+    /registration is closed/u
+  );
+  await runtime.shutdown();
+});
+
+test("feature actions publish explicit success events without service registrations", async () => {
+  let actions;
+  const received = [];
+  const feature = defineFeature({
+    id: "feature.event-proof",
+    domain: "books",
+    actions: [{
+      id: "books.save",
+      kind: "command",
+      channels: ["api"],
+      surfaces: ["app"],
+      input: emptyInput(),
+      idempotency: "none",
+      events: [createEntityChangedActionEvent({
+        source: "books",
+        entity: "book",
+        operation: "updated",
+        entityId: ({ context }) => context.actor.id,
+        realtime: {
+          event: "books.changed",
+          audience: "actor_user"
+        }
+      })],
+      async execute() {
+        return { saved: true };
+      }
+    }]
+  });
+  const listener = defineProvider({
+    id: "test.event-listener",
+    requires: {
+      actionCatalogue: "runtime.actions",
+      events: "runtime.events"
+    },
+    setup({ actionCatalogue, events }) {
+      actions = actionCatalogue;
+      events.register({ id: "test.capture", handle: (event) => received.push(event) });
+      return {};
+    }
+  });
+  const runtime = createCapabilityRuntime({
+    providers: [EventProvider, createActionProvider(), feature, listener]
+  });
+  await runtime.start();
+
+  await actions.execute({
+    actionId: "books.save",
+    input: {},
+    context: { channel: "api", surface: "app", actor: { id: "7" } }
+  });
+
+  assert.equal(received.length, 1);
+  assert.equal(received[0].type, "entity.changed");
+  assert.equal(received[0].entityId, "7");
+  assert.equal(received[0].realtime.event, "books.changed");
+  assert.equal(received[0].realtime.audience, "actor_user");
+});

package/server/features/index.js

@@ -0,0 +1 @@
+export { defineFeature } from "./defineFeature.js";

package/server/http/HttpProvider.js

@@ -0,0 +1,23 @@
+import { defineProvider } from "../../shared/capabilities/defineProvider.js";
+import { createCapabilityHttpRuntime } from "./capabilityHttpRuntime.js";
+
+const HttpProvider = defineProvider({
+  id: "runtime.http",
+  requires: {
+    actions: "runtime.actions",
+    fastify: "runtime.fastify"
+  },
+  provides: {
+    http: "runtime.http"
+  },
+  setup({ actions, fastify }) {
+    return {
+      http: createCapabilityHttpRuntime({ actions, fastify })
+    };
+  },
+  boot(_dependencies, { outputs }) {
+    outputs.http.start();
+  }
+});
+
+export { HttpProvider };

package/server/http/_testable/index.js

@@ -1,2 +1 @@
-export { createHttpRuntime } from "../lib/httpRuntime.js";
 export { compileRouteValidator } from "../lib/routeValidator.js";