@jskit-ai/kernel 0.1.244 → 0.1.246

package/server/runtime/entityChangeEvents.js

@@ -1,307 +0,0 @@
-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 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 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 normalizeMetaTextField(source = {}, fieldName = "", { context = "realtime entity change" } = {}) {
-  if (!Object.hasOwn(source, fieldName)) {
-    return "";
-  }
-
-  const value = source[fieldName];
-  if (value == null) {
-    return "";
-  }
-  if (typeof value !== "string") {
-    throw new TypeError(`${context}.${fieldName} must be a non-empty string.`);
-  }
-
-  const normalized = normalizeText(value);
-  if (!normalized) {
-    throw new TypeError(`${context}.${fieldName} must be a non-empty string.`);
-  }
-  return normalized;
-}
-
-function normalizeRealtimePayload(value, { context = "realtime entity change.payload" } = {}) {
-  if (value == null) {
-    return null;
-  }
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new TypeError(`${context} must be an object.`);
-  }
-  return Object.freeze({
-    ...value
-  });
-}
-
-function createRealtimeEntityChangeMeta({
-  serviceId,
-  methodName,
-  event,
-  change = {}
-} = {}) {
-  const source = normalizeObject(change);
-  const baseMeta = normalizeObject(source.meta);
-  const meta = {
-    ...baseMeta,
-    service: Object.freeze({
-      id: serviceId,
-      method: methodName
-    })
-  };
-
-  const action = normalizeMetaTextField(source, "action");
-  if (action) {
-    meta.action = action;
-  }
-
-  const reason = normalizeMetaTextField(source, "reason");
-  if (reason) {
-    meta.reason = reason;
-  }
-
-  const realtimeSource = normalizeObject(source.realtime);
-  const payloadSource = Object.hasOwn(source, "payload") ? source.payload : realtimeSource.payload;
-  const payload = normalizeRealtimePayload(payloadSource);
-  meta.realtime = payload
-    ? Object.freeze({
-        event,
-        payload
-      })
-    : Object.freeze({
-        event
-      });
-
-  return Object.freeze(meta);
-}
-
-function resolveRealtimeEntityChangeOptions(change = {}, options = {}) {
-  const source = normalizeObject(change);
-  if (Object.hasOwn(source, "options")) {
-    return normalizeObject(source.options);
-  }
-  return normalizeObject(options);
-}
-
-function createRealtimeEntityChangePublisher({
-  domainEvents,
-  source,
-  entity,
-  event,
-  serviceId,
-  methodName,
-  scopeResolver = resolveDefaultScope
-} = {}) {
-  const normalizedEvent = normalizeText(event);
-  if (!normalizedEvent) {
-    throw new TypeError("createRealtimeEntityChangePublisher requires event.");
-  }
-
-  const normalizedServiceId = normalizeText(serviceId);
-  if (!normalizedServiceId) {
-    throw new TypeError("createRealtimeEntityChangePublisher requires serviceId.");
-  }
-
-  const normalizedMethodName = normalizeText(methodName);
-  if (!normalizedMethodName) {
-    throw new TypeError("createRealtimeEntityChangePublisher requires methodName.");
-  }
-
-  const publishEntityChange = createEntityChangePublisher({
-    domainEvents,
-    source,
-    entity,
-    scopeResolver
-  });
-
-  return async function publishRealtimeEntityChange(operation, entityId, change = {}, options = {}) {
-    const runtimeOptions = resolveRealtimeEntityChangeOptions(change, options);
-    const meta = createRealtimeEntityChangeMeta({
-      serviceId: normalizedServiceId,
-      methodName: normalizedMethodName,
-      event: normalizedEvent,
-      change
-    });
-    return publishEntityChange(operation, entityId, runtimeOptions, meta);
-  };
-}
-
-function createNoopEntityChangePublisher() {
-  return async function publishEntityChange() {
-    return null;
-  };
-}
-
-export {
-  resolveDefaultScope,
-  createEntityChangePublisher,
-  createRealtimeEntityChangePublisher,
-  createNoopEntityChangePublisher
-};

package/server/runtime/entityChangeEvents.test.js

@@ -1,274 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import {
-  createEntityChangePublisher,
-  createRealtimeEntityChangePublisher
-} 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",
-        userId: "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);
-});
-
-test("realtime entity change publisher adds service, semantic, and realtime metadata", async () => {
-  const published = [];
-  const publishProjectChange = createRealtimeEntityChangePublisher({
-    domainEvents: {
-      async publish(payload) {
-        published.push(payload);
-      }
-    },
-    source: "vibe64",
-    entity: "project",
-    event: "vibe64.project.changed",
-    serviceId: "vibe64.terminals",
-    methodName: "projectRuntime"
-  });
-
-  const payload = await publishProjectChange("updated", "project_acme", {
-    action: "runtime-closed",
-    reason: "user-request",
-    payload: {
-      message: "Project is closed.",
-      runtime: {
-        open: false
-      }
-    },
-    options: {
-      context: {
-        actor: {
-          id: "user_17"
-        },
-        visibilityContext: {
-          scopeKind: "workspace",
-          scopeOwnerId: "workspace_23"
-        }
-      }
-    }
-  });
-
-  assert.equal(payload?.source, "vibe64");
-  assert.equal(payload?.entity, "project");
-  assert.equal(payload?.operation, "updated");
-  assert.equal(payload?.entityId, "project_acme");
-  assert.deepEqual(payload?.scope, {
-    kind: "workspace",
-    id: "workspace_23"
-  });
-  assert.equal(payload?.actorId, "user_17");
-  assert.equal(payload?.meta?.service?.id, "vibe64.terminals");
-  assert.equal(payload?.meta?.service?.method, "projectRuntime");
-  assert.equal(payload?.meta?.action, "runtime-closed");
-  assert.equal(payload?.meta?.reason, "user-request");
-  assert.equal(payload?.meta?.realtime?.event, "vibe64.project.changed");
-  assert.deepEqual(payload?.meta?.realtime?.payload, {
-    message: "Project is closed.",
-    runtime: {
-      open: false
-    }
-  });
-  assert.equal(published.length, 1);
-});