@jskit-ai/kernel 0.1.4

package/server/runtime/domainRules.test.js

@@ -0,0 +1,87 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { DomainValidationError } from "./errors.js";
+import { assertNoDomainRuleFailures, collectDomainFieldErrors } from "./domainRules.js";
+
+test("collectDomainFieldErrors collects string and object rule outcomes", () => {
+  const fieldErrors = collectDomainFieldErrors([
+    {
+      field: "name",
+      check: () => "name is required"
+    },
+    {
+      field: "email",
+      check: () => ({
+        message: "invalid email"
+      })
+    },
+    {
+      field: "country",
+      when: () => false,
+      check: () => "country not allowed"
+    }
+  ]);
+
+  assert.deepEqual(fieldErrors, {
+    name: "name is required",
+    email: "invalid email"
+  });
+});
+
+test("assertNoDomainRuleFailures does not throw when rules pass", () => {
+  assert.doesNotThrow(() =>
+    assertNoDomainRuleFailures([
+      {
+        field: "name",
+        check: () => null
+      }
+    ])
+  );
+});
+
+test("assertNoDomainRuleFailures throws DomainValidationError with fieldErrors", () => {
+  assert.throws(
+    () =>
+      assertNoDomainRuleFailures([
+        {
+          field: "plan",
+          check: () => "starter plan supports up to 200 employees"
+        }
+      ]),
+    (error) => {
+      assert.equal(error instanceof DomainValidationError, true);
+      assert.equal(error.code, "domain_validation_failed");
+      assert.deepEqual(error.details, {
+        fieldErrors: {
+          plan: "starter plan supports up to 200 employees"
+        }
+      });
+      return true;
+    }
+  );
+});
+
+test("assertNoDomainRuleFailures applies custom message and code", () => {
+  assert.throws(
+    () =>
+      assertNoDomainRuleFailures(
+        [
+          {
+            field: "email",
+            check: () => "email must include @"
+          }
+        ],
+        {
+          message: "Contact domain validation failed.",
+          code: "contact_domain_invalid"
+        }
+      ),
+    (error) => {
+      assert.equal(error instanceof DomainValidationError, true);
+      assert.equal(error.message, "Contact domain validation failed.");
+      assert.equal(error.code, "contact_domain_invalid");
+      return true;
+    }
+  );
+});

package/server/runtime/entityChangeEvents.js

@@ -0,0 +1,182 @@
+import { normalizeObject, normalizeOpaqueId, normalizeText } from "../../shared/support/normalize.js";
+import { resolveServiceContext } from "./serviceAuthorization.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 = {}, runtimeContext = {}) {
+  const visibility = normalizeText(visibilityContext.visibility).toLowerCase();
+  const scopeKind = normalizeText(visibilityContext.scopeKind || visibility).toLowerCase();
+  const scopeOwnerId = normalizeOpaqueId(visibilityContext.scopeOwnerId);
+  const userOwnerId = normalizeOpaqueId(visibilityContext.userOwnerId);
+  const requiresActorScope = visibilityContext.requiresActorScope === true;
+
+  if (requiresActorScope && userOwnerId == null) {
+    return null;
+  }
+
+  if (scopeKind && scopeOwnerId != null) {
+    const scope = {
+      kind: scopeKind,
+      id: scopeOwnerId
+    };
+    if (requiresActorScope) {
+      scope.scopeId = scopeOwnerId;
+      scope.userId = userOwnerId;
+    }
+    return scope;
+  }
+  if (scopeKind && scopeKind !== "user") {
+    return null;
+  }
+
+  if (!scopeKind && scopeOwnerId != null) {
+    return {
+      kind: "scope",
+      id: scopeOwnerId
+    };
+  }
+
+  if (scopeKind === "user" && userOwnerId != null) {
+    return {
+      kind: "user",
+      id: userOwnerId
+    };
+  }
+
+  return null;
+}
+
+function resolveDefaultScope(visibilityContext = {}, runtime = {}) {
+  const runtimeContext = normalizeObject(runtime?.context);
+
+  const visibilityScope = resolveVisibilityScope(visibilityContext, runtimeContext);
+  if (visibilityScope) {
+    return visibilityScope;
+  }
+
+  const contextScope = resolveContextScope(runtimeContext);
+  if (contextScope) {
+    return contextScope;
+  }
+
+  return {
+    kind: "global",
+    id: null
+  };
+}
+
+function resolveCommandId(requestMeta = {}) {
+  return normalizeText(requestMeta.commandId || requestMeta.idempotencyKey || "") || null;
+}
+
+function resolveSourceClientId(requestMeta = {}) {
+  return normalizeText(requestMeta.sourceClientId) || null;
+}
+
+function createEntityChangePublisher({
+  domainEvents,
+  source,
+  entity,
+  scopeResolver = resolveDefaultScope
+} = {}) {
+  if (!domainEvents || typeof domainEvents.publish !== "function") {
+    throw new TypeError("createEntityChangePublisher requires domainEvents.publish().");
+  }
+
+  const normalizedSource = normalizeText(source);
+  if (!normalizedSource) {
+    throw new TypeError("createEntityChangePublisher requires source.");
+  }
+
+  const normalizedEntity = normalizeText(entity);
+  if (!normalizedEntity) {
+    throw new TypeError("createEntityChangePublisher requires entity.");
+  }
+
+  return async function publishEntityChange(operation, entityId, options = {}, meta = null) {
+    const normalizedOperation = normalizeText(operation).toLowerCase();
+    if (!ENTITY_CHANGE_OPERATIONS.has(normalizedOperation)) {
+      throw new TypeError("publishEntityChange operation must be one of: created, updated, deleted.");
+    }
+
+    const normalizedEntityId = normalizeOpaqueId(entityId);
+    if (normalizedEntityId == null) {
+      return null;
+    }
+
+    const context = resolveServiceContext(options);
+    const requestMeta = normalizeObject(context.requestMeta);
+    const visibilityContext = normalizeObject(options.visibilityContext || context.visibilityContext);
+    const scope = scopeResolver(visibilityContext, {
+      context,
+      options
+    });
+
+    const payload = {
+      source: normalizedSource,
+      entity: normalizedEntity,
+      operation: normalizedOperation,
+      entityId: normalizedEntityId,
+      scope: scope && typeof scope === "object" ? scope : resolveDefaultScope(visibilityContext),
+      actorId: normalizeOpaqueId(context?.actor?.id),
+      commandId: resolveCommandId(requestMeta),
+      sourceClientId: resolveSourceClientId(requestMeta),
+      occurredAt: new Date().toISOString()
+    };
+    const normalizedMeta = normalizeObject(meta);
+    if (Object.keys(normalizedMeta).length > 0) {
+      payload.meta = normalizedMeta;
+    }
+
+    await domainEvents.publish(payload);
+    return payload;
+  };
+}
+
+function createNoopEntityChangePublisher() {
+  return async function publishEntityChange() {
+    return null;
+  };
+}
+
+export {
+  resolveDefaultScope,
+  createEntityChangePublisher,
+  createNoopEntityChangePublisher
+};

package/server/runtime/entityChangeEvents.test.js

@@ -0,0 +1,211 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createEntityChangePublisher } from "./entityChangeEvents.js";
+
+test("entity change publisher emits normalized event payload", async () => {
+  const published = [];
+  const publishEntityChange = createEntityChangePublisher({
+    domainEvents: {
+      async publish(payload) {
+        published.push(payload);
+      }
+    },
+    source: "crud",
+    entity: "record"
+  });
+
+  const payload = await publishEntityChange("created", 5, {
+    context: {
+      actor: { id: 17 },
+      requestMeta: {
+        commandId: "cmd-1",
+        sourceClientId: "client-a"
+      },
+      visibilityContext: {
+        scopeOwnerId: 23
+      }
+    }
+  }, {
+    service: {
+      token: "crud.customers",
+      method: "createRecord"
+    }
+  });
+
+  assert.equal(payload?.operation, "created");
+  assert.equal(payload?.entityId, 5);
+  assert.deepEqual(payload?.scope, { kind: "scope", id: 23 });
+  assert.equal(payload?.actorId, 17);
+  assert.equal(payload?.commandId, "cmd-1");
+  assert.equal(payload?.sourceClientId, "client-a");
+  assert.equal(payload?.meta?.service?.token, "crud.customers");
+  assert.equal(payload?.meta?.service?.method, "createRecord");
+  assert.equal(published.length, 1);
+});
+
+test("entity change publisher accepts opaque entity identifiers", async () => {
+  const published = [];
+  const publishEntityChange = createEntityChangePublisher({
+    domainEvents: {
+      async publish(payload) {
+        published.push(payload);
+      }
+    },
+    source: "crud",
+    entity: "record"
+  });
+
+  const payload = await publishEntityChange("updated", "record_4f5d2f6a-607e-4b4b-9bfa-4f8c2b1d3c8e");
+
+  assert.equal(payload?.entityId, "record_4f5d2f6a-607e-4b4b-9bfa-4f8c2b1d3c8e");
+  assert.equal(published.length, 1);
+});
+
+test("entity change publisher ignores missing entity identifiers", async () => {
+  const published = [];
+  const publishEntityChange = createEntityChangePublisher({
+    domainEvents: {
+      async publish(payload) {
+        published.push(payload);
+      }
+    },
+    source: "crud",
+    entity: "record"
+  });
+
+  const payload = await publishEntityChange("updated", null);
+
+  assert.equal(payload, null);
+  assert.equal(published.length, 0);
+});
+
+test("entity change publisher infers scoped owner from service context when visibility owner ids are missing", async () => {
+  const published = [];
+  const publishEntityChange = createEntityChangePublisher({
+    domainEvents: {
+      async publish(payload) {
+        published.push(payload);
+      }
+    },
+    source: "workspace",
+    entity: "settings"
+  });
+
+  const payload = await publishEntityChange(
+    "updated",
+    11,
+    {
+      context: {
+        actor: { id: 17 },
+        scope: { kind: "workspace", id: 23 },
+        visibilityContext: {
+          visibility: "workspace"
+        }
+      }
+    },
+    {
+      service: {
+        token: "users.workspace.settings.service",
+        method: "updateWorkspaceSettings"
+      }
+    }
+  );
+
+  assert.deepEqual(payload?.scope, { kind: "workspace", id: 23 });
+  assert.equal(published.length, 1);
+});
+
+test("entity change publisher supports opaque actor and scope identifiers", async () => {
+  const published = [];
+  const publishEntityChange = createEntityChangePublisher({
+    domainEvents: {
+      async publish(payload) {
+        published.push(payload);
+      }
+    },
+    source: "workspace",
+    entity: "settings"
+  });
+
+  const payload = await publishEntityChange("updated", 11, {
+    context: {
+      actor: { id: "user_17" },
+      visibilityContext: {
+        scopeKind: "workspace_user",
+        scopeOwnerId: "workspace_23",
+        userOwnerId: "user_17",
+        requiresActorScope: true
+      }
+    }
+  });
+
+  assert.deepEqual(payload?.scope, {
+    kind: "workspace_user",
+    id: "workspace_23",
+    scopeId: "workspace_23",
+    userId: "user_17"
+  });
+  assert.equal(payload?.actorId, "user_17");
+  assert.equal(published.length, 1);
+});
+
+test("entity change publisher does not infer actor-scoped ownership from actor.id", async () => {
+  const published = [];
+  const publishEntityChange = createEntityChangePublisher({
+    domainEvents: {
+      async publish(payload) {
+        published.push(payload);
+      }
+    },
+    source: "workspace",
+    entity: "settings"
+  });
+
+  const payload = await publishEntityChange("updated", 11, {
+    context: {
+      actor: { id: "user_17" },
+      visibilityContext: {
+        scopeKind: "workspace_user",
+        scopeOwnerId: "workspace_23",
+        requiresActorScope: true
+      }
+    }
+  });
+
+  assert.deepEqual(payload?.scope, {
+    kind: "global",
+    id: null
+  });
+  assert.equal(payload?.actorId, "user_17");
+  assert.equal(published.length, 1);
+});
+
+test("entity change publisher does not infer actor scope from scope kind suffix", async () => {
+  const published = [];
+  const publishEntityChange = createEntityChangePublisher({
+    domainEvents: {
+      async publish(payload) {
+        published.push(payload);
+      }
+    },
+    source: "workspace",
+    entity: "settings"
+  });
+
+  const payload = await publishEntityChange("updated", 11, {
+    context: {
+      visibilityContext: {
+        scopeKind: "workspace_user",
+        scopeOwnerId: "workspace_23",
+        requiresActorScope: false
+      }
+    }
+  });
+
+  assert.deepEqual(payload?.scope, {
+    kind: "workspace_user",
+    id: "workspace_23"
+  });
+  assert.equal(payload?.actorId, null);
+  assert.equal(published.length, 1);
+});

package/server/runtime/errors.js

@@ -0,0 +1,68 @@
+export class AppError extends Error {
+  constructor(status, message, options = {}) {
+    super(message);
+    this.name = "AppError";
+    this.status = Number(status) || 500;
+    this.statusCode = this.status;
+    this.code = options.code || "APP_ERROR";
+    this.details = options.details;
+    this.headers = options.headers || {};
+  }
+}
+
+export class DomainError extends AppError {
+  constructor(status, message, options = {}) {
+    super(status, message, {
+      ...options,
+      code: options.code || "domain_error"
+    });
+    this.name = "DomainError";
+  }
+}
+
+export class DomainValidationError extends DomainError {
+  constructor(details, options = {}) {
+    super(422, options.message || "Domain validation failed.", {
+      ...options,
+      code: options.code || "domain_validation_failed",
+      details
+    });
+    this.name = "DomainValidationError";
+  }
+}
+
+export class ConflictError extends DomainError {
+  constructor(message = "Conflict.", options = {}) {
+    super(409, message, {
+      ...options,
+      code: options.code || "conflict"
+    });
+    this.name = "ConflictError";
+  }
+}
+
+export class NotFoundError extends DomainError {
+  constructor(message = "Not found.", options = {}) {
+    super(404, message, {
+      ...options,
+      code: options.code || "not_found"
+    });
+    this.name = "NotFoundError";
+  }
+}
+
+export function isAppError(error) {
+  return error instanceof AppError;
+}
+
+export function isDomainError(error) {
+  return error instanceof DomainError;
+}
+
+export function createValidationError(fieldErrors) {
+  return new AppError(400, "Validation failed.", {
+    details: {
+      fieldErrors
+    }
+  });
+}

package/server/runtime/errors.test.js

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  AppError,
+  DomainError,
+  DomainValidationError,
+  ConflictError,
+  NotFoundError,
+  isAppError,
+  isDomainError,
+  createValidationError
+} from "./errors.js";
+
+test("DomainValidationError defaults to 422 and domain_validation_failed", () => {
+  const error = new DomainValidationError(["email is required"]);
+
+  assert.equal(error.status, 422);
+  assert.equal(error.statusCode, 422);
+  assert.equal(error.code, "domain_validation_failed");
+  assert.equal(error.message, "Domain validation failed.");
+  assert.deepEqual(error.details, ["email is required"]);
+  assert.equal(error.name, "DomainValidationError");
+});
+
+test("ConflictError defaults to 409 and conflict", () => {
+  const error = new ConflictError("Duplicate contact.", {
+    details: { email: "alice@example.com" }
+  });
+
+  assert.equal(error.status, 409);
+  assert.equal(error.code, "conflict");
+  assert.equal(error.message, "Duplicate contact.");
+  assert.deepEqual(error.details, { email: "alice@example.com" });
+  assert.equal(error.name, "ConflictError");
+});
+
+test("NotFoundError defaults to 404 and not_found", () => {
+  const error = new NotFoundError("Contact not found.", {
+    details: { id: "contact-1" }
+  });
+
+  assert.equal(error.status, 404);
+  assert.equal(error.code, "not_found");
+  assert.equal(error.message, "Contact not found.");
+  assert.deepEqual(error.details, { id: "contact-1" });
+  assert.equal(error.name, "NotFoundError");
+});
+
+test("isDomainError identifies DomainError subclasses and isAppError remains true", () => {
+  const domainError = new DomainError(422, "Domain failed.", {
+    code: "domain_failed"
+  });
+
+  assert.equal(isDomainError(domainError), true);
+  assert.equal(isAppError(domainError), true);
+
+  const appError = new AppError(500, "App failed.");
+  assert.equal(isDomainError(appError), false);
+  assert.equal(isAppError(appError), true);
+});
+
+test("createValidationError remains compatible", () => {
+  const error = createValidationError({ email: "Invalid." });
+
+  assert.equal(error.status, 400);
+  assert.equal(error.message, "Validation failed.");
+  assert.deepEqual(error.details, {
+    fieldErrors: {
+      email: "Invalid."
+    }
+  });
+});