@jskit-ai/kernel 0.1.97 → 0.1.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.97",
+  "version": "0.1.99",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "1.x.x"
@@ -29,6 +29,7 @@
     "./server/platform": "./server/platform/index.js",
     "./server/registries": "./server/registries/index.js",
     "./server/runtime": "./server/runtime/index.js",
+    "./server/runtime/entityChangeEvents": "./server/runtime/entityChangeEvents.js",
     "./server/runtime/errors": "./server/runtime/errors.js",
     "./server/runtime/requestUrl": "./server/runtime/requestUrl.js",
     "./server/support": "./server/support/index.js",

package/server/registries/serviceRegistrationRegistry.js

@@ -60,6 +60,25 @@ function normalizeServiceEventEntityId(value) {
   return null;
 }
 
+function normalizeServiceEventMetaField(value, { context = "service event meta field" } = {}) {
+  if (value == null) {
+    return null;
+  }
+
+  if (typeof value === "function") {
+    return value;
+  }
+  if (typeof value !== "string") {
+    throw new TypeError(`${context} must be a non-empty string or function.`);
+  }
+
+  const normalized = normalizeText(value);
+  if (!normalized) {
+    throw new TypeError(`${context} must be a non-empty string or function.`);
+  }
+  return normalized;
+}
+
 function normalizeRealtimeDispatch(value, { context = "service event.realtime" } = {}) {
   const source = normalizeObject(value);
   if (Object.keys(source).length < 1) {
@@ -118,6 +137,8 @@ function normalizeServiceEventSpec(entry, { context = "service event" } = {}) {
     entity: normalizeText(source.entity),
     operation: normalizeServiceEventOperation(source.operation, { context }),
     entityId: normalizeServiceEventEntityId(source.entityId),
+    action: normalizeServiceEventMetaField(source.action, { context: `${context}.action` }),
+    reason: normalizeServiceEventMetaField(source.reason, { context: `${context}.reason` }),
     realtime: normalizeRealtimeDispatch(source.realtime, { context: `${context}.realtime` })
   });
 }
@@ -230,6 +251,28 @@ function resolveEventEntityId(spec, state) {
   return state?.result?.id;
 }
 
+function resolveEventMetaField(value, state) {
+  const context = `service metadata.events.${state.methodName}.meta`;
+  if (typeof value === "function") {
+    const resolved = value({
+      result: state.result,
+      args: state.args,
+      options: state.options,
+      methodName: state.methodName,
+      serviceToken: state.serviceToken,
+      event: state.event
+    });
+    if (resolved == null) {
+      return "";
+    }
+    if (typeof resolved !== "string") {
+      throw new TypeError(`${context} field resolver must return a string.`);
+    }
+    return normalizeText(resolved);
+  }
+  return normalizeText(value);
+}
+
 function resolveEventMeta(spec, state) {
   const meta = {
     service: Object.freeze({
@@ -238,6 +281,22 @@ function resolveEventMeta(spec, state) {
     })
   };
 
+  const action = resolveEventMetaField(spec.action, {
+    ...state,
+    event: spec
+  });
+  if (action) {
+    meta.action = action;
+  }
+
+  const reason = resolveEventMetaField(spec.reason, {
+    ...state,
+    event: spec
+  });
+  if (reason) {
+    meta.reason = reason;
+  }
+
   if (spec.realtime) {
     meta.realtime = spec.realtime.payload
       ? Object.freeze({

package/server/runtime/entityChangeEvents.js

@@ -1,3 +1,4 @@
+import { isContainerToken } from "../../shared/support/containerToken.js";
 import { normalizeObject, normalizeOpaqueId, normalizeText } from "../../shared/support/normalize.js";
 import { resolveServiceContext } from "./serviceAuthorization.js";
 
@@ -169,6 +170,129 @@ function createEntityChangePublisher({
   };
 }
 
+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({
+  serviceToken,
+  methodName,
+  event,
+  change = {}
+} = {}) {
+  const source = normalizeObject(change);
+  const baseMeta = normalizeObject(source.meta);
+  const meta = {
+    ...baseMeta,
+    service: Object.freeze({
+      token: serviceToken,
+      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,
+  serviceToken,
+  methodName,
+  scopeResolver = resolveDefaultScope
+} = {}) {
+  const normalizedEvent = normalizeText(event);
+  if (!normalizedEvent) {
+    throw new TypeError("createRealtimeEntityChangePublisher requires event.");
+  }
+
+  if (!isContainerToken(serviceToken)) {
+    throw new TypeError("createRealtimeEntityChangePublisher requires a valid serviceToken.");
+  }
+
+  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({
+      serviceToken,
+      methodName: normalizedMethodName,
+      event: normalizedEvent,
+      change
+    });
+    return publishEntityChange(operation, entityId, runtimeOptions, meta);
+  };
+}
+
 function createNoopEntityChangePublisher() {
   return async function publishEntityChange() {
     return null;
@@ -178,5 +302,6 @@ function createNoopEntityChangePublisher() {
 export {
   resolveDefaultScope,
   createEntityChangePublisher,
+  createRealtimeEntityChangePublisher,
   createNoopEntityChangePublisher
 };

package/server/runtime/entityChangeEvents.test.js

@@ -1,6 +1,9 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { createEntityChangePublisher } from "./entityChangeEvents.js";
+import {
+  createEntityChangePublisher,
+  createRealtimeEntityChangePublisher
+} from "./entityChangeEvents.js";
 
 test("entity change publisher emits normalized event payload", async () => {
   const published = [];
@@ -209,3 +212,63 @@ test("entity change publisher does not infer actor scope from scope kind suffix"
   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",
+    serviceToken: "vibe64.terminals.service",
+    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?.token, "vibe64.terminals.service");
+  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);
+});

package/server/runtime/serviceRegistration.test.js

@@ -93,6 +93,64 @@ test("app.service rejects deprecated permissions metadata", () => {
   );
 });
 
+test("app.service publishes lifecycle action, reason, and realtime payload metadata", async () => {
+  const app = createContainer();
+  const published = [];
+  app.singleton("domainEvents", () => ({
+    async publish(payload) {
+      published.push(payload);
+      return null;
+    }
+  }));
+  installServiceRegistrationApi(app);
+
+  app.service(
+    "test.projects.service",
+    () => ({
+      async closeRuntime() {
+        return {
+          id: "project_acme",
+          action: "runtime-closed",
+          message: "Project is closed."
+        };
+      }
+    }),
+    {
+      events: {
+        closeRuntime: [
+          {
+            type: "entity.changed",
+            source: "vibe64",
+            entity: "project",
+            operation: "updated",
+            action: ({ result }) => result?.action,
+            reason: "user-request",
+            realtime: {
+              event: "vibe64.project.changed",
+              payload: ({ result }) => ({
+                message: result?.message || ""
+              })
+            }
+          }
+        ]
+      }
+    }
+  );
+
+  const service = app.make("test.projects.service");
+  await service.closeRuntime();
+
+  assert.equal(service.serviceEvents.closeRuntime[0].reason, "user-request");
+  assert.equal(typeof service.serviceEvents.closeRuntime[0].action, "function");
+  assert.equal(published.length, 1);
+  assert.equal(published[0].meta?.action, "runtime-closed");
+  assert.equal(published[0].meta?.reason, "user-request");
+  assert.equal(published[0].meta?.realtime?.event, "vibe64.project.changed");
+  assert.deepEqual(published[0].meta?.realtime?.payload, {
+    message: "Project is closed."
+  });
+});
+
 test("resolveServiceRegistrations returns declared service metadata", () => {
   const app = createContainer();
   app.singleton("domainEvents", () => ({

package/test/exportsContract.test.js

@@ -25,7 +25,9 @@ const EXPORTED_UNUSED_ALLOWLIST = new Set([
   // Used by generated app bootstrap code emitted from kernel client vite plugin.
   "./client/moduleBootstrap",
   // Intentionally retained as an explicit low-level kernel API subpath.
-  "./shared/support/tokens"
+  "./shared/support/tokens",
+  // Public helper API for packages that publish entity-change realtime events.
+  "./server/runtime/entityChangeEvents"
 ]);
 
 function normalizeSlash(value) {