@jskit-ai/kernel 0.1.245 → 0.1.247

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"
+  });
+});

package/server/actions/actionEvents.js

@@ -1,8 +1,103 @@
-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 resolveContextScope(context = {}) {
+  const sourceScope = normalizeObject(context?.scope || context?.requestMeta?.scope || context?.request?.scope);
+  const kind = normalizeText(sourceScope.kind).toLowerCase();
+  if (!kind) {
+    return null;
+  }
+  if (kind === "global") {
+    return {
+      kind: "global",
+      id: null
+    };
+  }
+
+  const scopeId = normalizeOpaqueId(sourceScope.id);
+  if (scopeId == null) {
+    return null;
+  }
+
+  const resolvedScope = {
+    kind,
+    id: scopeId
+  };
+
+  const scopeUserId = normalizeOpaqueId(sourceScope.userId);
+  if (scopeUserId != null) {
+    resolvedScope.userId = scopeUserId;
+  }
+
+  const scopedScopeId = normalizeOpaqueId(sourceScope.scopeId);
+  if (scopedScopeId != null) {
+    resolvedScope.scopeId = scopedScopeId;
+  }
+
+  return resolvedScope;
+}
+
+function resolveVisibilityScope(visibilityContext = {}) {
+  const visibility = normalizeText(visibilityContext.visibility).toLowerCase();
+  const scopeKind = normalizeText(visibilityContext.scopeKind || visibility).toLowerCase();
+  const scopeOwnerId = normalizeOpaqueId(visibilityContext.scopeOwnerId);
+  const userId = normalizeOpaqueId(visibilityContext.userId);
+  const requiresActorScope = visibilityContext.requiresActorScope === true;
+
+  if (requiresActorScope && userId == null) {
+    return null;
+  }
+
+  if (scopeKind && scopeOwnerId != null) {
+    const scope = {
+      kind: scopeKind,
+      id: scopeOwnerId
+    };
+    if (requiresActorScope) {
+      scope.scopeId = scopeOwnerId;
+      scope.userId = userId;
+    }
+    return scope;
+  }
+  if (scopeKind && scopeKind !== "user") {
+    return null;
+  }
+
+  if (!scopeKind && scopeOwnerId != null) {
+    return {
+      kind: "scope",
+      id: scopeOwnerId
+    };
+  }
+
+  if (scopeKind === "user" && userId != null) {
+    return {
+      kind: "user",
+      id: userId
+    };
+  }
+
+  return null;
+}
+
+function resolveEventScope(context = {}) {
+  const visibilityScope = resolveVisibilityScope(normalizeObject(context.visibilityContext));
+  if (visibilityScope) {
+    return visibilityScope;
+  }
+
+  const contextScope = resolveContextScope(context);
+  if (contextScope) {
+    return contextScope;
+  }
+
+  return {
+    kind: "global",
+    id: null
+  };
+}
+
 function resolveValue(value, execution) {
   return typeof value === "function" ? value(execution) : value;
 }
@@ -53,7 +148,7 @@ function createEntityChangedActionEvent({
       entity: normalizedEntity,
       operation: normalizedOperation,
       entityId: normalizedEntityId,
-      scope: resolveDefaultScope(normalizeObject(context.visibilityContext), { context }),
+      scope: resolveEventScope(context),
       actorId: normalizeOpaqueId(context?.actor?.id),
       commandId: normalizeText(requestMeta.commandId || requestMeta.idempotencyKey) || null,
       sourceClientId: normalizeText(requestMeta.sourceClientId) || null,

package/server/actions/actionEvents.test.js

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createEntityChangedActionEvent } from "./actionEvents.js";
+
+function buildEvent(context, { entityId = 11, realtime = null } = {}) {
+  return createEntityChangedActionEvent({
+    source: "workspace",
+    entity: "settings",
+    operation: "updated",
+    entityId,
+    realtime
+  })({ context });
+}
+
+test("entity-changed action events carry actor, command and source client", () => {
+  const event = buildEvent({
+    actor: { id: 17 },
+    requestMeta: { idempotencyKey: "cmd-1", sourceClientId: "client-a" },
+    visibilityContext: { scopeOwnerId: 23 }
+  }, {
+    entityId: 5,
+    realtime: { event: "settings.changed", payload: { reason: "edit" } }
+  });
+
+  assert.equal(event.type, "entity.changed");
+  assert.equal(event.entityId, "5");
+  assert.deepEqual(event.scope, { kind: "scope", id: "23" });
+  assert.equal(event.actorId, "17");
+  assert.equal(event.commandId, "cmd-1");
+  assert.equal(event.sourceClientId, "client-a");
+  assert.deepEqual(event.realtime, { event: "settings.changed", audience: "event_scope", payload: { reason: "edit" } });
+});
+
+test("entity-changed action events skip missing entity identifiers", () => {
+  assert.equal(buildEvent({}, { entityId: null }), null);
+});
+
+test("entity-changed action events fall back to the context scope when visibility has no owner", () => {
+  const event = buildEvent({
+    scope: { kind: "workspace", id: 23 },
+    visibilityContext: { visibility: "workspace" }
+  });
+
+  assert.deepEqual(event.scope, { kind: "workspace", id: "23" });
+});
+
+test("entity-changed action events keep actor-scoped ownership only with an explicit user", () => {
+  assert.deepEqual(buildEvent({
+    actor: { id: "user_17" },
+    visibilityContext: {
+      scopeKind: "workspace_user",
+      scopeOwnerId: "workspace_23",
+      userId: "user_17",
+      requiresActorScope: true
+    }
+  }).scope, {
+    kind: "workspace_user",
+    id: "workspace_23",
+    scopeId: "workspace_23",
+    userId: "user_17"
+  });
+
+  assert.deepEqual(buildEvent({
+    actor: { id: "user_17" },
+    visibilityContext: {
+      scopeKind: "workspace_user",
+      scopeOwnerId: "workspace_23",
+      requiresActorScope: true
+    }
+  }).scope, { kind: "global", id: null });
+
+  assert.deepEqual(buildEvent({
+    visibilityContext: {
+      scopeKind: "workspace_user",
+      scopeOwnerId: "workspace_23",
+      requiresActorScope: false
+    }
+  }).scope, { kind: "workspace_user", id: "workspace_23" });
+});

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

@@ -1,6 +1,6 @@
 import { normalizeRequestMeta } from "./requestMeta.js";
-import { normalizeLowerText, normalizeText } from "./textNormalization.js";
-import { normalizePermissionList } from "../support/permissions.js";
+import { normalizeLowerText, normalizeText } from "../../shared/support/normalize.js";
+import { normalizePermissionList } from "../../shared/support/permissions.js";
 
 function copyRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -73,14 +73,4 @@ function normalizeExecutionContext(context = {}) {
   });
 }
 
-const __testables = {
-  normalizeText,
-  normalizeLowerText,
-  normalizePermissions: normalizePermissionList,
-  copyRecord,
-  normalizeActor,
-  normalizeRequestMeta,
-  normalizeTimeMeta
-};
-
-export { normalizeExecutionContext, __testables };
+export { normalizeExecutionContext };

package/server/actions/idempotency.js

@@ -0,0 +1,24 @@
+import { createActionRuntimeError } from "./actionDefinitions.js";
+import { normalizeText } from "../../shared/support/normalize.js";
+
+function ensureIdempotencyKeyIfRequired(definition, context) {
+  if (definition.idempotency !== "required") {
+    return;
+  }
+
+  const key = normalizeText(context?.requestMeta?.idempotencyKey || context?.requestMeta?.commandId);
+  if (key) {
+    return;
+  }
+
+  throw createActionRuntimeError(400, "Validation failed.", {
+    code: "ACTION_IDEMPOTENCY_KEY_REQUIRED",
+    details: {
+      fieldErrors: {
+        idempotencyKey: "Idempotency key is required for this action."
+      }
+    }
+  });
+}
+
+export { ensureIdempotencyKeyIfRequired };

package/server/actions/pipeline.js

@@ -0,0 +1,87 @@
+import {
+  ensureActionChannelAllowed,
+  ensureActionSurfaceAllowed,
+  ensureActionPermissionAllowed,
+  normalizeActionInput,
+  normalizeActionOutput
+} from "./policies.js";
+import { ensureIdempotencyKeyIfRequired } from "./idempotency.js";
+import { normalizeExecutionContext } from "./executionContext.js";
+
+async function publishActionEvents(events, builders, execution) {
+  if (!Array.isArray(builders) || builders.length === 0) return;
+  if (!events || typeof events.publish !== "function") {
+    throw new TypeError("Action event publishing requires runtime.events.publish().");
+  }
+  for (const builder of builders) {
+    const built = await builder(execution);
+    const values = Array.isArray(built) ? built : [built];
+    for (const event of values) {
+      if (event != null) await events.publish(event);
+    }
+  }
+}
+
+function logActionExecution(logger, { definition, context, outcome, startedAt, errorCode = null }) {
+  if (!logger || typeof logger.debug !== "function") {
+    return;
+  }
+  logger.debug(
+    {
+      action: definition?.id,
+      version: definition?.version,
+      channel: context?.channel,
+      surface: context?.surface,
+      requestId: context?.requestMeta?.requestId || null,
+      durationMs: Date.now() - startedAt,
+      outcome,
+      errorCode
+    },
+    "action.execution"
+  );
+}
+
+async function executeActionPipeline({
+  definition,
+  input,
+  context,
+  deps = {},
+  events,
+  logger = console
+} = {}) {
+  const normalizedContext = normalizeExecutionContext(context);
+  const startedAt = Date.now();
+
+  try {
+    ensureActionChannelAllowed(definition, normalizedContext);
+    ensureActionSurfaceAllowed(definition, normalizedContext);
+    ensureActionPermissionAllowed(definition, normalizedContext);
+
+    const normalizedInput = await normalizeActionInput(definition, input);
+    ensureIdempotencyKeyIfRequired(definition, normalizedContext);
+
+    const executionResult = await definition.execute(normalizedInput, normalizedContext, deps);
+    const normalizedResult = await normalizeActionOutput(definition, executionResult);
+
+    await publishActionEvents(events, definition.events, Object.freeze({
+      definition,
+      input: normalizedInput,
+      result: normalizedResult,
+      context: normalizedContext
+    }));
+
+    logActionExecution(logger, { definition, context: normalizedContext, outcome: "success", startedAt });
+    return normalizedResult;
+  } catch (error) {
+    logActionExecution(logger, {
+      definition,
+      context: normalizedContext,
+      outcome: "failure",
+      startedAt,
+      errorCode: String(error?.code || "ACTION_EXECUTION_FAILED").trim()
+    });
+    throw error;
+  }
+}
+
+export { executeActionPipeline };

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

@@ -1,10 +1,7 @@
 import { createActionRuntimeError } from "./actionDefinitions.js";
-import { normalizeLowerText, normalizeText } from "./textNormalization.js";
-import { hasPermission, normalizePermissionList } from "../support/permissions.js";
-import { isRecord, normalizeOpaqueId } from "../support/normalize.js";
-import {
-  validateSchemaPayload
-} from "../validators/schemaPayloadValidation.js";
+import { hasPermission, normalizePermissionList } from "../../shared/support/permissions.js";
+import { isRecord, normalizeLowerText, normalizeOpaqueId } from "../../shared/support/normalize.js";
+import { validateSchemaPayload } from "../../shared/validators/schemaPayloadValidation.js";
 
 function createActionValidationError({
   status = 400,
@@ -22,13 +19,12 @@ function createActionValidationError({
 
 function ensureActionChannelAllowed(definition, context) {
   const channel = normalizeLowerText(context?.channel);
-  const allowedChannels = Array.isArray(definition?.channels) ? definition.channels : [];
 
-  if (!channel || !allowedChannels.includes(channel)) {
+  if (!channel || !definition.channels.includes(channel)) {
     throw createActionRuntimeError(403, "Forbidden.", {
       code: "ACTION_CHANNEL_FORBIDDEN",
       details: {
-        actionId: definition?.id,
+        actionId: definition.id,
         channel
       }
     });
@@ -37,13 +33,13 @@ function ensureActionChannelAllowed(definition, context) {
 
 function ensureActionSurfaceAllowed(definition, context) {
   const surface = normalizeLowerText(context?.surface);
-  const allowedSurfaces = Array.isArray(definition?.surfaces) ? definition.surfaces : [];
+  const allowedSurfaces = definition.surfaces;
 
   if (!allowedSurfaces.includes("*") && (!surface || !allowedSurfaces.includes(surface))) {
     throw createActionRuntimeError(403, "Forbidden.", {
       code: "ACTION_SURFACE_FORBIDDEN",
       details: {
-        actionId: definition?.id,
+        actionId: definition.id,
         surface
       }
     });
@@ -51,8 +47,8 @@ function ensureActionSurfaceAllowed(definition, context) {
 }
 
 function ensureActionPermissionAllowed(definition, context) {
-  const permission = isRecord(definition?.permission) ? definition.permission : { require: "none" };
-  const mode = normalizeLowerText(permission.require || "none");
+  const { permission } = definition;
+  const mode = permission.require;
 
   if (mode === "none") {
     return;
@@ -63,7 +59,7 @@ function ensureActionPermissionAllowed(definition, context) {
     throw createActionRuntimeError(401, permission.message || "Authentication required.", {
       code: permission.code || "ACTION_AUTHENTICATION_REQUIRED",
       details: {
-        actionId: definition?.id
+        actionId: definition.id
       }
     });
   }
@@ -72,7 +68,7 @@ function ensureActionPermissionAllowed(definition, context) {
     return;
   }
 
-  const requiredPermissions = normalizePermissionList(permission.permissions);
+  const requiredPermissions = permission.permissions;
   if (requiredPermissions.length < 1) {
     return;
   }
@@ -87,7 +83,7 @@ function ensureActionPermissionAllowed(definition, context) {
       throw createActionRuntimeError(403, permission.message || "Forbidden.", {
         code: permission.code || "ACTION_PERMISSION_DENIED",
         details: {
-          actionId: definition?.id,
+          actionId: definition.id,
           permission: requiredPermission
         }
       });
@@ -101,19 +97,18 @@ function ensureActionPermissionAllowed(definition, context) {
     throw createActionRuntimeError(403, permission.message || "Forbidden.", {
       code: permission.code || "ACTION_PERMISSION_DENIED",
       details: {
-        actionId: definition?.id,
+        actionId: definition.id,
         requiredPermissions
       }
     });
   }
 }
 
-async function normalizeActionInput(definition, input, context) {
+async function normalizeActionInput(definition, input) {
   try {
-    return validateSchemaPayload(definition?.input, input, {
+    return validateSchemaPayload(definition.input, input, {
       phase: "input",
-      definition,
-      context
+      context: `Action ${definition.id} input`
     });
   } catch (error) {
     if (isRecord(error?.fieldErrors) || isRecord(error?.details?.fieldErrors)) {
@@ -137,16 +132,15 @@ async function normalizeActionInput(definition, input, context) {
   }
 }
 
-async function normalizeActionOutput(definition, output, context) {
-  if (!definition?.output) {
+async function normalizeActionOutput(definition, output) {
+  if (!definition.output) {
     return output;
   }
 
   try {
     return validateSchemaPayload(definition.output, output, {
       phase: "output",
-      definition,
-      context
+      context: `Action ${definition.id} output`
     });
   } catch (error) {
     if (isRecord(error?.fieldErrors) || isRecord(error?.details?.fieldErrors)) {
@@ -182,17 +176,10 @@ async function normalizeActionOutput(definition, output, context) {
   }
 }
 
-const __testables = {
-  normalizeText,
-  normalizeLowerText,
-  validateSchemaPayload
-};
-
 export {
   ensureActionChannelAllowed,
   ensureActionSurfaceAllowed,
   ensureActionPermissionAllowed,
   normalizeActionInput,
-  normalizeActionOutput,
-  __testables
+  normalizeActionOutput
 };