@jskit-ai/kernel 0.1.4

package/server/runtime/apiRouteRegistration.js

@@ -0,0 +1,65 @@
+import { defaultMissingHandler } from "./routeUtils.js";
+import { defaultApplyRoutePolicy, normalizeRoutePolicyConfig } from "../support/routePolicyConfig.js";
+import { isRecord } from "../../shared/support/normalize.js";
+
+function buildBaseRouteOptions(route) {
+  if (!isRecord(route)) {
+    throw new TypeError("Route definition must be an object.");
+  }
+
+  const sourceRoute = route;
+  const routeOptions = {
+    method: sourceRoute.method,
+    url: sourceRoute.path,
+    config: {}
+  };
+
+  if (sourceRoute.schema) {
+    routeOptions.schema = sourceRoute.schema;
+  }
+  if (sourceRoute.bodyLimit) {
+    routeOptions.bodyLimit = sourceRoute.bodyLimit;
+  }
+  if (sourceRoute.rateLimit) {
+    routeOptions.config.rateLimit = sourceRoute.rateLimit;
+  }
+
+  return routeOptions;
+}
+
+function registerApiRouteDefinitions(
+  fastify,
+  { routes = [], applyRoutePolicy = defaultApplyRoutePolicy, resolveRequestUrl = null, missingHandler } = {}
+) {
+  if (!fastify || typeof fastify.route !== "function") {
+    throw new TypeError("registerApiRouteDefinitions requires a Fastify instance.");
+  }
+
+  const routeList = Array.isArray(routes) ? routes : [];
+  const toRequestUrl = typeof resolveRequestUrl === "function" ? resolveRequestUrl : () => null;
+  const routePolicyApplier = typeof applyRoutePolicy === "function" ? applyRoutePolicy : defaultApplyRoutePolicy;
+  const fallbackHandler = typeof missingHandler === "function" ? missingHandler : defaultMissingHandler;
+
+  for (const route of routeList) {
+    const routeOptions = routePolicyApplier(buildBaseRouteOptions(route), route);
+    let routeHandler = fallbackHandler;
+    if (isRecord(route) && typeof route.handler === "function") {
+      routeHandler = route.handler;
+    }
+    fastify.route({
+      ...routeOptions,
+      handler: async (request, reply) => {
+        await routeHandler(request, reply, toRequestUrl(request));
+      }
+    });
+  }
+}
+
+const __testables = {
+  buildBaseRouteOptions,
+  defaultApplyRoutePolicy,
+  normalizeRoutePolicyConfig,
+  defaultMissingHandler
+};
+
+export { registerApiRouteDefinitions, __testables };

package/server/runtime/bootBootstrapRoutes.js

@@ -0,0 +1,46 @@
+import { Type } from "typebox";
+import { normalizeObjectInput } from "../../shared/validators/inputNormalization.js";
+import { AUTH_POLICY_PUBLIC } from "../../shared/support/policies.js";
+import { KERNEL_TOKENS } from "../../shared/support/tokens.js";
+import { resolveBootstrapPayload } from "../registries/bootstrapPayloadContributorRegistry.js";
+
+const bootstrapQueryValidator = Object.freeze({
+  schema: Type.Object({}, { additionalProperties: true }),
+  normalize: normalizeObjectInput
+});
+
+const bootstrapOutputValidator = Object.freeze({
+  schema: Type.Object({}, { additionalProperties: true }),
+  normalize: normalizeObjectInput
+});
+
+function bootBootstrapRoutes(app) {
+  const router = app.make(KERNEL_TOKENS.HttpRouter);
+
+  router.register(
+    "GET",
+    "/api/bootstrap",
+    {
+      auth: AUTH_POLICY_PUBLIC,
+      meta: {
+        tags: ["bootstrap"],
+        summary: "Resolve app bootstrap payload from registered contributors"
+      },
+      queryValidator: bootstrapQueryValidator,
+      responseValidators: {
+        200: bootstrapOutputValidator
+      }
+    },
+    async function (request, reply) {
+      const payload = await resolveBootstrapPayload(app, {
+        request,
+        reply,
+        query: request.input?.query || {}
+      });
+
+      reply.code(200).send(payload);
+    }
+  );
+}
+
+export { bootBootstrapRoutes, bootstrapQueryValidator, bootstrapOutputValidator };

package/server/runtime/bootBootstrapRoutes.test.js

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createContainer } from "../container/index.js";
+import { KERNEL_TOKENS } from "../../shared/support/tokens.js";
+import { registerBootstrapPayloadContributor } from "../registries/bootstrapPayloadContributorRegistry.js";
+import { bootBootstrapRoutes, bootstrapQueryValidator } from "./bootBootstrapRoutes.js";
+
+function createReplyDouble() {
+  return {
+    statusCode: 200,
+    payload: null,
+    code(value) {
+      this.statusCode = value;
+      return this;
+    },
+    send(value) {
+      this.payload = value;
+      return this;
+    }
+  };
+}
+
+test("bootstrapQueryValidator normalizes generic query payloads", () => {
+  assert.deepEqual(bootstrapQueryValidator.normalize({}), {});
+  assert.deepEqual(bootstrapQueryValidator.normalize({ workspaceSlug: "  AcMe  ", page: "1" }), {
+    workspaceSlug: "  AcMe  ",
+    page: "1"
+  });
+});
+
+test("bootBootstrapRoutes registers GET /api/bootstrap and resolves contributors", async () => {
+  const app = createContainer();
+  const routes = [];
+  const router = {
+    register(method, path, route, handler) {
+      routes.push({
+        method,
+        path,
+        route,
+        handler
+      });
+    }
+  };
+
+  app.instance(KERNEL_TOKENS.HttpRouter, router);
+  registerBootstrapPayloadContributor(app, "test.bootstrap.payload", () => ({
+    contributorId: "test.bootstrap.payload",
+    contribute({ query }) {
+      return {
+        source: "test",
+        workspaceSlug: query.workspaceSlug
+      };
+    }
+  }));
+
+  bootBootstrapRoutes(app);
+
+  const bootstrapRoute = routes.find((entry) => entry.method === "GET" && entry.path === "/api/bootstrap");
+  assert.ok(bootstrapRoute);
+  assert.equal(typeof bootstrapRoute.route.queryValidator.normalize, "function");
+
+  const reply = createReplyDouble();
+  await bootstrapRoute.handler(
+    {
+      input: {
+        query: {
+          workspaceSlug: "acme"
+        }
+      }
+    },
+    reply
+  );
+
+  assert.equal(reply.statusCode, 200);
+  assert.deepEqual(reply.payload, {
+    source: "test",
+    workspaceSlug: "acme"
+  });
+});

package/server/runtime/bootstrapContributors.test.js

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createContainer } from "../container/index.js";
+import {
+  registerBootstrapPayloadContributor,
+  resolveBootstrapPayloadContributors,
+  resolveBootstrapPayload
+} from "../registries/bootstrapPayloadContributorRegistry.js";
+
+test("registerBootstrapPayloadContributor + resolveBootstrapPayloadContributors register canonical contributors", () => {
+  const app = createContainer();
+
+  registerBootstrapPayloadContributor(app, "test.bootstrap.alpha", () => ({
+    contributorId: "alpha",
+    contribute() {
+      return {
+        alpha: true
+      };
+    }
+  }));
+
+  const contributors = resolveBootstrapPayloadContributors(app);
+  assert.equal(contributors.length, 1);
+  assert.equal(contributors[0].contributorId, "alpha");
+  assert.equal(typeof contributors[0].contribute, "function");
+});
+
+test("resolveBootstrapPayload applies contributors in deterministic token order", async () => {
+  const app = createContainer();
+  const calls = [];
+
+  registerBootstrapPayloadContributor(app, "test.bootstrap.zeta", () => ({
+    contributorId: "zeta",
+    contribute({ payload, query }) {
+      calls.push({
+        contributorId: "zeta",
+        payload,
+        query
+      });
+      return {
+        last: true
+      };
+    }
+  }));
+
+  registerBootstrapPayloadContributor(app, "test.bootstrap.alpha", () => ({
+    contributorId: "alpha",
+    contribute({ payload, query }) {
+      calls.push({
+        contributorId: "alpha",
+        payload,
+        query
+      });
+      return {
+        first: true
+      };
+    }
+  }));
+
+  const payload = await resolveBootstrapPayload(app, {
+    query: {
+      workspaceSlug: "acme"
+    }
+  });
+
+  assert.deepEqual(calls, [
+    {
+      contributorId: "alpha",
+      payload: {},
+      query: {
+        workspaceSlug: "acme"
+      }
+    },
+    {
+      contributorId: "zeta",
+      payload: {
+        first: true
+      },
+      query: {
+        workspaceSlug: "acme"
+      }
+    }
+  ]);
+  assert.deepEqual(payload, {
+    first: true,
+    last: true
+  });
+});
+
+test("resolveBootstrapPayload ignores non-object contributions", async () => {
+  const app = createContainer();
+
+  registerBootstrapPayloadContributor(app, "test.bootstrap.noop", () => ({
+    contributorId: "noop",
+    contribute() {
+      return null;
+    }
+  }));
+  registerBootstrapPayloadContributor(app, "test.bootstrap.ok", () => ({
+    contributorId: "ok",
+    contribute() {
+      return {
+        ok: true
+      };
+    }
+  }));
+
+  const payload = await resolveBootstrapPayload(app, {
+    ignored: true
+  });
+  assert.deepEqual(payload, {
+    ok: true
+  });
+});

package/server/runtime/canonicalJson.js

@@ -0,0 +1,74 @@
+import crypto from "node:crypto";
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value) && value.constructor === Object;
+}
+
+function sortValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortValue);
+  }
+
+  if (isPlainObject(value)) {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      const next = value[key];
+      if (next === undefined) {
+        continue;
+      }
+      sorted[key] = sortValue(next);
+    }
+    return sorted;
+  }
+
+  return value;
+}
+
+function toCanonicalJson(value) {
+  return JSON.stringify(sortValue(value));
+}
+
+function toSha256Hex(value) {
+  const source = String(value || "");
+  return crypto.createHash("sha256").update(source).digest("hex");
+}
+
+function toHmacSha256Hex(secret, value) {
+  const normalizedSecret = String(secret || "").trim();
+  if (!normalizedSecret) {
+    throw new Error("HMAC secret is required.");
+  }
+
+  return crypto
+    .createHmac("sha256", normalizedSecret)
+    .update(String(value || ""))
+    .digest("hex");
+}
+
+function safeParseJson(value, fallback = null) {
+  if (value == null) {
+    return fallback;
+  }
+
+  if (typeof value === "object") {
+    return value;
+  }
+
+  const text = String(value || "").trim();
+  if (!text) {
+    return fallback;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+
+const __testables = {
+  isPlainObject,
+  sortValue
+};
+
+export { toCanonicalJson, toSha256Hex, toHmacSha256Hex, safeParseJson, __testables };

package/server/runtime/composition.js

@@ -0,0 +1,142 @@
+function normalizeRegistryDefinitions(definitions, { registryKind = "registry" } = {}) {
+  const source = Array.isArray(definitions) ? definitions : [];
+  const normalized = [];
+  const seenIds = new Set();
+
+  for (const entry of source) {
+    const id = String(entry?.id || "").trim();
+    const create = entry?.create;
+
+    if (!id) {
+      throw new TypeError(`${registryKind} definition id is required.`);
+    }
+    if (seenIds.has(id)) {
+      throw new TypeError(`${registryKind} definition "${id}" is duplicated.`);
+    }
+    if (typeof create !== "function") {
+      throw new TypeError(`${registryKind} definition "${id}" create must be a function.`);
+    }
+
+    seenIds.add(id);
+    normalized.push({
+      id,
+      create
+    });
+  }
+
+  return normalized;
+}
+
+function createRegistryFromDefinitions(definitions, createArgsFactory, options = {}) {
+  const normalizedDefinitions = normalizeRegistryDefinitions(definitions, options);
+  const registry = {};
+
+  for (const definition of normalizedDefinitions) {
+    const createArgs =
+      typeof createArgsFactory === "function" ? createArgsFactory({ definition, registry }) : Object.freeze({});
+    registry[definition.id] = definition.create(createArgs || {});
+  }
+
+  return registry;
+}
+
+function createRepositoryRegistry(definitions) {
+  return createRegistryFromDefinitions(definitions, () => ({}), {
+    registryKind: "repository"
+  });
+}
+
+function createServiceRegistry({ definitions, dependencies = {} } = {}) {
+  return createRegistryFromDefinitions(
+    definitions,
+    ({ registry }) => ({
+      ...(dependencies || {}),
+      services: registry
+    }),
+    {
+      registryKind: "service"
+    }
+  );
+}
+
+function createControllerRegistry({ definitions, services = {}, dependencies = {} } = {}) {
+  return createRegistryFromDefinitions(
+    definitions,
+    ({ registry }) => ({
+      ...(dependencies || {}),
+      services,
+      controllers: registry
+    }),
+    {
+      registryKind: "controller"
+    }
+  );
+}
+
+function selectRuntimeServices(services, selectedIds = []) {
+  const source = services && typeof services === "object" ? services : {};
+  const ids = Array.isArray(selectedIds) ? selectedIds : [];
+  const runtimeServices = {};
+
+  for (const rawId of ids) {
+    const id = String(rawId || "").trim();
+    if (!id) {
+      continue;
+    }
+    if (!Object.hasOwn(source, id)) {
+      throw new Error(`Runtime service "${id}" is not defined.`);
+    }
+    runtimeServices[id] = source[id];
+  }
+
+  return runtimeServices;
+}
+
+function createRuntimeComposition({
+  repositoryDefinitions = [],
+  serviceDefinitions = [],
+  controllerDefinitions = [],
+  runtimeServiceIds = [],
+  repositoryDependencies = {},
+  serviceDependencies = {},
+  controllerDependencies = {}
+} = {}) {
+  const repositories = createRepositoryRegistry(repositoryDefinitions);
+  const services = createServiceRegistry({
+    definitions: serviceDefinitions,
+    dependencies: {
+      ...(repositoryDependencies || {}),
+      ...(serviceDependencies || {}),
+      repositories
+    }
+  });
+  const controllers = createControllerRegistry({
+    definitions: controllerDefinitions,
+    services,
+    dependencies: {
+      ...(controllerDependencies || {})
+    }
+  });
+  const runtimeServices = selectRuntimeServices(services, runtimeServiceIds);
+
+  return {
+    repositories,
+    services,
+    controllers,
+    runtimeServices
+  };
+}
+
+const __testables = {
+  normalizeRegistryDefinitions,
+  createRegistryFromDefinitions
+};
+
+export {
+  createRepositoryRegistry,
+  createServiceRegistry,
+  createControllerRegistry,
+  selectRuntimeServices,
+  createRuntimeComposition,
+  __testables
+};

package/server/runtime/domainEvents.test.js

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createContainer } from "../container/index.js";
+import {
+  registerDomainEventListener,
+  resolveDomainEventListeners,
+  createDomainEvents
+} from "../registries/domainEventListenerRegistry.js";
+
+test("registerDomainEventListener + resolveDomainEventListeners resolve canonical listeners", () => {
+  const app = createContainer();
+
+  registerDomainEventListener(app, "test.domainEvents.alpha", () => ({
+    listenerId: "alpha",
+    async handle() {}
+  }));
+  registerDomainEventListener(app, "test.domainEvents.zeta", () => ({
+    listenerId: "zeta",
+    async handle() {}
+  }));
+
+  const listeners = resolveDomainEventListeners(app);
+  assert.deepEqual(
+    listeners.map((listener) => listener.listenerId),
+    ["alpha", "zeta"]
+  );
+  assert.equal(typeof listeners[0].handle, "function");
+  assert.equal(typeof listeners[1].handle, "function");
+});
+
+test("createDomainEvents.publish dispatches listeners and applies matches filter", async () => {
+  const app = createContainer();
+  const calls = [];
+
+  registerDomainEventListener(app, "test.domainEvents.alpha", () => ({
+    listenerId: "alpha",
+    matches(event) {
+      return event.entity === "record";
+    },
+    async handle(event) {
+      calls.push({
+        listenerId: "alpha",
+        event
+      });
+    }
+  }));
+  registerDomainEventListener(app, "test.domainEvents.beta", () => ({
+    listenerId: "beta",
+    async handle(event) {
+      calls.push({
+        listenerId: "beta",
+        event
+      });
+    }
+  }));
+
+  const domainEvents = createDomainEvents(app);
+  await domainEvents.publish({
+    entity: "record",
+    operation: "created"
+  });
+  await domainEvents.publish({
+    entity: "other",
+    operation: "created"
+  });
+
+  assert.deepEqual(calls, [
+    {
+      listenerId: "alpha",
+      event: {
+        entity: "record",
+        operation: "created"
+      }
+    },
+    {
+      listenerId: "beta",
+      event: {
+        entity: "record",
+        operation: "created"
+      }
+    },
+    {
+      listenerId: "beta",
+      event: {
+        entity: "other",
+        operation: "created"
+      }
+    }
+  ]);
+});
+
+test("createDomainEvents.publish ignores non-listener tag entries", async () => {
+  const app = createContainer();
+
+  registerDomainEventListener(app, "test.domainEvents.invalid", () => ({
+    listenerId: "invalid"
+  }));
+  registerDomainEventListener(app, "test.domainEvents.valid", () => ({
+    listenerId: "valid",
+    async handle() {}
+  }));
+
+  const listeners = resolveDomainEventListeners(app);
+  assert.deepEqual(
+    listeners.map((listener) => listener.listenerId),
+    ["valid"]
+  );
+
+  const domainEvents = createDomainEvents(app);
+  const result = await domainEvents.publish({
+    entity: "record"
+  });
+  assert.equal(result, null);
+});

package/server/runtime/domainRules.js

@@ -0,0 +1,50 @@
+import { DomainValidationError } from "./errors.js";
+
+function collectDomainFieldErrors(rules) {
+  const fieldErrors = {};
+
+  for (const rule of Array.isArray(rules) ? rules : []) {
+    if (rule?.when && !rule.when()) {
+      continue;
+    }
+
+    const outcome = rule?.check ? rule.check() : null;
+    if (!outcome) {
+      continue;
+    }
+
+    if (typeof outcome === "string") {
+      fieldErrors[rule.field] = outcome;
+      continue;
+    }
+
+    if (typeof outcome === "object") {
+      fieldErrors[rule.field] = outcome?.message || "domain rule failed";
+    }
+  }
+
+  return fieldErrors;
+}
+
+function assertNoDomainRuleFailures(
+  rules,
+  {
+    message = "Domain validation failed.",
+    code = "domain_validation_failed"
+  } = {}
+) {
+  const fieldErrors = collectDomainFieldErrors(rules);
+  if (Object.keys(fieldErrors).length > 0) {
+    throw new DomainValidationError(
+      {
+        fieldErrors
+      },
+      {
+        message,
+        code
+      }
+    );
+  }
+}
+
+export { collectDomainFieldErrors, assertNoDomainRuleFailures };