@jskit-ai/kernel 0.1.245 → 0.1.246

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
 };

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

@@ -20,7 +20,7 @@ test("plain json-rest-schema action schemas validate input without reshaping it"
     }
   };
 
-  const result = await normalizeActionInput(definition, { workspaceSlug: "  ACME  " }, {});
+  const result = await normalizeActionInput(definition, { workspaceSlug: "  ACME  " });
   assert.deepEqual(result, { workspaceSlug: "ACME" });
 });
 
@@ -41,7 +41,7 @@ test("json-rest-schema input validation surfaces plain field keys", async () =>
   };
 
   await assert.rejects(
-    () => normalizeActionInput(definition, { name: "too long" }, {}),
+    () => normalizeActionInput(definition, { name: "too long" }),
     (error) => {
       const fieldErrors = error.details?.fieldErrors || {};
       assert.equal(typeof fieldErrors.name, "string");
@@ -67,11 +67,11 @@ test("action output validation preserves valid json-rest-schema output", async (
   };
 
   await assert.rejects(
-    () => normalizeActionOutput(definition, { ok: 2 }, {}),
+    () => normalizeActionOutput(definition, { ok: 2 }),
     (error) => error?.code === "ACTION_OUTPUT_VALIDATION_FAILED"
   );
 
-  const result = await normalizeActionOutput(definition, { ok: true }, {});
+  const result = await normalizeActionOutput(definition, { ok: true });
   assert.deepEqual(result, { ok: true });
 });
 
@@ -94,7 +94,7 @@ test("json-rest-schema action validators normalize action input", async () => {
     }
   };
 
-  const result = await normalizeActionInput(definition, { name: "  Acme  " }, {});
+  const result = await normalizeActionInput(definition, { name: "  Acme  " });
   assert.deepEqual(result, { name: "Acme" });
 });
 
@@ -118,7 +118,7 @@ test("json-rest-schema action validators surface field errors", async () => {
   };
 
   await assert.rejects(
-    () => normalizeActionInput(definition, { name: "   " }, {}),
+    () => normalizeActionInput(definition, { name: "   " }),
     (error) => {
       assert.equal(error.code, "ACTION_VALIDATION_FAILED");
       assert.equal(error.details?.fieldErrors?.name, "Name is required.");

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

@@ -111,9 +111,6 @@ function resolveActionDefinition(index, actionId, version) {
 
 function createActionRegistry({
   contributors = [],
-  idempotencyAdapter,
-  auditAdapter,
-  observabilityAdapter,
   events,
   logger = console
 } = {}) {
@@ -122,19 +119,14 @@ function createActionRegistry({
 
   async function execute({ actionId, version = null, input = {}, context = {}, deps = {} } = {}) {
     const definition = resolveActionDefinition(index, actionId, version);
-    const execution = await executeActionPipeline({
+    return executeActionPipeline({
       definition,
       input,
       context,
       deps,
-      idempotencyAdapter,
-      auditAdapter,
-      observabilityAdapter,
       events,
       logger
     });
-
-    return execution.result;
   }
 
   async function executeStream({ actionId, version = null, input = {}, context = {}, deps = {} } = {}) {
@@ -150,19 +142,14 @@ function createActionRegistry({
       });
     }
 
-    const execution = await executeActionPipeline({
+    return executeActionPipeline({
       definition,
       input,
       context,
       deps,
-      idempotencyAdapter,
-      auditAdapter,
-      observabilityAdapter,
       events,
       logger
     });
-
-    return execution.result;
   }
 
   function listDefinitions() {
@@ -181,10 +168,4 @@ function createActionRegistry({
   });
 }
 
-const __testables = {
-  normalizeContributors,
-  buildDefinitionIndex,
-  resolveActionDefinition
-};
-
-export { createActionRegistry, __testables };
+export { createActionRegistry };