@jskit-ai/kernel 0.1.4

package/shared/actions/executionContext.js

@@ -0,0 +1,97 @@
+import { normalizeRequestMeta } from "./requestMeta.js";
+import { normalizeLowerText, normalizeText } from "./textNormalization.js";
+
+function normalizePermissions(value) {
+  const source = Array.isArray(value) ? value : [];
+  return Array.from(new Set(source.map((entry) => normalizeText(entry)).filter(Boolean)));
+}
+
+function copyRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  return {
+    ...value
+  };
+}
+
+function normalizeActor(actor) {
+  const source = copyRecord(actor);
+  if (!source) {
+    return null;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(source, "id")) {
+    source.id = null;
+  } else if (source.id == null) {
+    source.id = null;
+  }
+
+  return source;
+}
+
+function normalizeMembership(membership) {
+  return copyRecord(membership);
+}
+
+function normalizeTimeMeta(timeMeta) {
+  const source = timeMeta && typeof timeMeta === "object" ? timeMeta : {};
+  const nowValue = source.now instanceof Date ? source.now : new Date();
+
+  return {
+    now: nowValue,
+    timezone: normalizeText(source.timezone),
+    locale: normalizeText(source.locale)
+  };
+}
+
+const RESERVED_CONTEXT_KEYS = new Set([
+  "actor",
+  "membership",
+  "permissions",
+  "surface",
+  "channel",
+  "requestMeta",
+  "timeMeta"
+]);
+
+function copyPassthroughContextEntries(source = {}) {
+  const passthrough = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (RESERVED_CONTEXT_KEYS.has(key)) {
+      continue;
+    }
+    passthrough[key] = value;
+  }
+  return passthrough;
+}
+
+function normalizeExecutionContext(context = {}) {
+  const source = context && typeof context === "object" ? context : {};
+  const passthrough = copyPassthroughContextEntries(source);
+
+  return Object.freeze({
+    ...passthrough,
+    actor: normalizeActor(source.actor),
+    membership: normalizeMembership(source.membership),
+    permissions: normalizePermissions(source.permissions),
+    surface: normalizeLowerText(source.surface),
+    channel: normalizeLowerText(source.channel) || "internal",
+    requestMeta: normalizeRequestMeta(source.requestMeta),
+    timeMeta: normalizeTimeMeta(source.timeMeta)
+  });
+}
+
+const __testables = {
+  normalizeText,
+  normalizeLowerText,
+  normalizePermissions,
+  copyRecord,
+  normalizeActor,
+  normalizeMembership,
+  normalizeRequestMeta,
+  normalizeTimeMeta
+};
+
+export { normalizeExecutionContext, __testables };

package/shared/actions/executionContext.test.js

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { normalizeExecutionContext } from "./executionContext.js";
+
+test("normalizeExecutionContext preserves non-core context fields", () => {
+  const context = normalizeExecutionContext({
+    tenant: {
+      id: 7,
+      slug: "team-alpha",
+      ownerUserId: 42
+    }
+  });
+
+  assert.equal(context.tenant.ownerUserId, 42);
+});
+
+test("normalizeExecutionContext keeps custom requestMeta fields", () => {
+  const resolvedWorkspaceContext = {
+    workspace: {
+      id: 7,
+      ownerUserId: 42
+    }
+  };
+
+  const context = normalizeExecutionContext({
+    requestMeta: {
+      resolvedWorkspaceContext
+    }
+  });
+
+  assert.deepEqual(context.requestMeta.resolvedWorkspaceContext, resolvedWorkspaceContext);
+});
+
+test("normalizeExecutionContext leaves surface empty when missing", () => {
+  const context = normalizeExecutionContext({});
+  assert.equal(context.surface, "");
+});
+
+test("normalizeExecutionContext keeps actor payload generic", () => {
+  const context = normalizeExecutionContext({
+    actor: {
+      id: "user_1",
+      email: "UPPER@EXAMPLE.COM",
+      roleId: "OWNER",
+      customFlag: true
+    },
+    membership: {
+      roleId: "OWNER",
+      status: "ACTIVE",
+      extra: "x"
+    }
+  });
+
+  assert.deepEqual(context.actor, {
+    id: "user_1",
+    email: "UPPER@EXAMPLE.COM",
+    roleId: "OWNER",
+    customFlag: true
+  });
+  assert.deepEqual(context.membership, {
+    roleId: "OWNER",
+    status: "ACTIVE",
+    extra: "x"
+  });
+});

package/shared/actions/idempotency.js

@@ -0,0 +1,62 @@
+import { createActionRuntimeError } from "./actionDefinitions.js";
+import { normalizeText } from "./textNormalization.js";
+
+function resolveRequestIdempotencyKey(context) {
+  return normalizeText(context?.requestMeta?.idempotencyKey || context?.requestMeta?.commandId || "");
+}
+
+function resolveActionIdempotencyKey(definition, context) {
+  const policy = normalizeText(definition?.idempotency || "none").toLowerCase();
+  if (policy === "none") {
+    return "";
+  }
+
+  return resolveRequestIdempotencyKey(context);
+}
+
+function createNoopIdempotencyAdapter() {
+  return {
+    async claimOrReplay() {
+      return {
+        type: "proceed",
+        idempotencyReplay: false,
+        claim: null,
+        replayResult: null
+      };
+    },
+    async markSucceeded() {},
+    async markFailed() {}
+  };
+}
+
+function ensureIdempotencyKeyIfRequired(definition, context, key) {
+  const policy = normalizeText(definition?.idempotency || "none").toLowerCase();
+  if (policy !== "required") {
+    return;
+  }
+
+  if (normalizeText(key)) {
+    return;
+  }
+
+  throw createActionRuntimeError(400, "Validation failed.", {
+    code: "ACTION_IDEMPOTENCY_KEY_REQUIRED",
+    details: {
+      fieldErrors: {
+        idempotencyKey: "Idempotency key is required for this action."
+      }
+    }
+  });
+}
+
+const __testables = {
+  normalizeText,
+  resolveRequestIdempotencyKey
+};
+
+export {
+  resolveActionIdempotencyKey,
+  ensureIdempotencyKeyIfRequired,
+  createNoopIdempotencyAdapter,
+  __testables
+};

package/shared/actions/index.js

@@ -0,0 +1,2 @@
+export { normalizeActionDefinition } from "./actionDefinitions.js";
+export { withActionDefaults } from "./withActionDefaults.js";

package/shared/actions/observability.js

@@ -0,0 +1,10 @@
+function createNoopObservabilityAdapter() {
+  return {
+    recordExecutionStart() {},
+    recordExecutionFinish() {},
+    recordValidationFailure() {},
+    recordIdempotentReplay() {}
+  };
+}
+
+export { createNoopObservabilityAdapter };

package/shared/actions/pipeline.js

@@ -0,0 +1,287 @@
+import {
+  ensureActionChannelAllowed,
+  ensureActionSurfaceAllowed,
+  ensureActionPermissionAllowed,
+  normalizeActionInput,
+  normalizeActionOutput
+} from "./policies.js";
+import {
+  createNoopIdempotencyAdapter,
+  resolveActionIdempotencyKey,
+  ensureIdempotencyKeyIfRequired
+} from "./idempotency.js";
+import { createNoopAuditAdapter } from "./audit.js";
+import { createNoopObservabilityAdapter } from "./observability.js";
+import { normalizeExecutionContext } from "./executionContext.js";
+
+function normalizeOutcomeErrorCode(error) {
+  return String(error?.code || "ACTION_EXECUTION_FAILED").trim();
+}
+
+function buildActionLogPayload({ definition, context, outcome, durationMs, errorCode, idempotencyReplay }) {
+  return {
+    action: definition?.id,
+    version: definition?.version,
+    channel: context?.channel,
+    surface: context?.surface,
+    requestId: context?.requestMeta?.requestId || null,
+    durationMs,
+    outcome,
+    errorCode: errorCode || null,
+    idempotencyReplay: Boolean(idempotencyReplay)
+  };
+}
+
+async function emitAuditEvent(adapter, payload) {
+  if (!adapter || typeof adapter.emitExecution !== "function") {
+    return;
+  }
+
+  await adapter.emitExecution(payload);
+}
+
+async function executeIdempotencyClaim(adapter, payload) {
+  if (!adapter || typeof adapter.claimOrReplay !== "function") {
+    return {
+      type: "proceed",
+      idempotencyReplay: false,
+      claim: null,
+      replayResult: null
+    };
+  }
+
+  const result = await adapter.claimOrReplay(payload);
+  if (!result || typeof result !== "object") {
+    return {
+      type: "proceed",
+      idempotencyReplay: false,
+      claim: null,
+      replayResult: null
+    };
+  }
+
+  return {
+    type: String(result.type || "proceed"),
+    idempotencyReplay: result.idempotencyReplay === true,
+    claim: result.claim || null,
+    replayResult: Object.hasOwn(result, "replayResult") ? result.replayResult : null
+  };
+}
+
+async function executeActionPipeline({
+  definition,
+  input,
+  context,
+  deps = {},
+  idempotencyAdapter,
+  auditAdapter,
+  observabilityAdapter,
+  logger = console
+} = {}) {
+  const normalizedContext = normalizeExecutionContext(context);
+  const normalizedIdempotencyAdapter = idempotencyAdapter || createNoopIdempotencyAdapter();
+  const normalizedAuditAdapter = auditAdapter || createNoopAuditAdapter();
+  const normalizedObservabilityAdapter = observabilityAdapter || createNoopObservabilityAdapter();
+  const startedAt = Date.now();
+
+  if (typeof normalizedObservabilityAdapter.recordExecutionStart === "function") {
+    normalizedObservabilityAdapter.recordExecutionStart({
+      definition,
+      context: normalizedContext
+    });
+  }
+
+  let idempotencyKey = "";
+  let idempotencyClaim = null;
+
+  try {
+    ensureActionChannelAllowed(definition, normalizedContext);
+    ensureActionSurfaceAllowed(definition, normalizedContext);
+    ensureActionPermissionAllowed(definition, normalizedContext);
+
+    const normalizedInput = await normalizeActionInput(definition, input, normalizedContext);
+
+    idempotencyKey = resolveActionIdempotencyKey(definition, normalizedContext);
+    ensureIdempotencyKeyIfRequired(definition, normalizedContext, idempotencyKey);
+
+    const idempotencyPolicy = String(definition?.idempotency || "none").trim().toLowerCase();
+    if (idempotencyPolicy !== "none") {
+      const claimResult = await executeIdempotencyClaim(normalizedIdempotencyAdapter, {
+        definition,
+        context: normalizedContext,
+        input: normalizedInput,
+        idempotencyKey
+      });
+
+      idempotencyClaim = claimResult.claim;
+      if (claimResult.type === "replay") {
+        if (typeof normalizedObservabilityAdapter.recordIdempotentReplay === "function") {
+          normalizedObservabilityAdapter.recordIdempotentReplay({
+            definition,
+            context: normalizedContext
+          });
+        }
+
+        const replayDurationMs = Date.now() - startedAt;
+        if (typeof normalizedObservabilityAdapter.recordExecutionFinish === "function") {
+          normalizedObservabilityAdapter.recordExecutionFinish({
+            definition,
+            context: normalizedContext,
+            outcome: "replay",
+            durationMs: replayDurationMs,
+            idempotencyReplay: true
+          });
+        }
+
+        await emitAuditEvent(normalizedAuditAdapter, {
+          definition,
+          context: normalizedContext,
+          outcome: "success",
+          result: claimResult.replayResult,
+          error: null,
+          durationMs: replayDurationMs,
+          idempotencyReplay: true
+        });
+
+        if (logger && typeof logger.debug === "function") {
+          logger.debug(
+            buildActionLogPayload({
+              definition,
+              context: normalizedContext,
+              outcome: "replay",
+              durationMs: replayDurationMs,
+              errorCode: null,
+              idempotencyReplay: true
+            }),
+            "action.execution"
+          );
+        }
+
+        return {
+          result: claimResult.replayResult,
+          idempotencyReplay: true
+        };
+      }
+    }
+
+    const executionResult = await definition.execute(normalizedInput, normalizedContext, deps);
+    const normalizedResult = await normalizeActionOutput(definition, executionResult, normalizedContext);
+
+    if (idempotencyClaim && typeof normalizedIdempotencyAdapter.markSucceeded === "function") {
+      await normalizedIdempotencyAdapter.markSucceeded({
+        definition,
+        context: normalizedContext,
+        input: normalizedInput,
+        result: normalizedResult,
+        claim: idempotencyClaim,
+        idempotencyKey
+      });
+    }
+
+    const durationMs = Date.now() - startedAt;
+    if (typeof normalizedObservabilityAdapter.recordExecutionFinish === "function") {
+      normalizedObservabilityAdapter.recordExecutionFinish({
+        definition,
+        context: normalizedContext,
+        outcome: "success",
+        durationMs,
+        idempotencyReplay: false
+      });
+    }
+
+    await emitAuditEvent(normalizedAuditAdapter, {
+      definition,
+      context: normalizedContext,
+      outcome: "success",
+      result: normalizedResult,
+      error: null,
+      durationMs,
+      idempotencyReplay: false
+    });
+
+    if (logger && typeof logger.debug === "function") {
+      logger.debug(
+        buildActionLogPayload({
+          definition,
+          context: normalizedContext,
+          outcome: "success",
+          durationMs,
+          errorCode: null,
+          idempotencyReplay: false
+        }),
+        "action.execution"
+      );
+    }
+
+    return {
+      result: normalizedResult,
+      idempotencyReplay: false
+    };
+  } catch (error) {
+    const executionError = error;
+
+    if (executionError?.code === "ACTION_VALIDATION_FAILED") {
+      if (typeof normalizedObservabilityAdapter.recordValidationFailure === "function") {
+        normalizedObservabilityAdapter.recordValidationFailure({
+          definition,
+          context: normalizedContext,
+          error: executionError
+        });
+      }
+    }
+
+    if (idempotencyClaim && typeof normalizedIdempotencyAdapter.markFailed === "function") {
+      await normalizedIdempotencyAdapter.markFailed({
+        definition,
+        context: normalizedContext,
+        input,
+        error: executionError,
+        claim: idempotencyClaim,
+        idempotencyKey
+      });
+    }
+
+    const durationMs = Date.now() - startedAt;
+    const errorCode = normalizeOutcomeErrorCode(executionError);
+
+    if (typeof normalizedObservabilityAdapter.recordExecutionFinish === "function") {
+      normalizedObservabilityAdapter.recordExecutionFinish({
+        definition,
+        context: normalizedContext,
+        outcome: "failure",
+        durationMs,
+        error: executionError,
+        errorCode,
+        idempotencyReplay: false
+      });
+    }
+
+    await emitAuditEvent(normalizedAuditAdapter, {
+      definition,
+      context: normalizedContext,
+      outcome: "failure",
+      result: null,
+      error: executionError,
+      durationMs,
+      idempotencyReplay: false
+    });
+
+    if (logger && typeof logger.debug === "function") {
+      logger.debug(
+        buildActionLogPayload({
+          definition,
+          context: normalizedContext,
+          outcome: "failure",
+          durationMs,
+          errorCode,
+          idempotencyReplay: false
+        }),
+        "action.execution"
+      );
+    }
+
+    throw executionError;
+  }
+}
+
+export { executeActionPipeline };