@jskit-ai/kernel 0.1.159 → 0.1.161

package/shared/capabilities/defineProvider.js

@@ -0,0 +1,99 @@
+import { isRecord } from "../support/normalize.js";
+
+const ARCHITECTURE_ID_PATTERN = /^[a-z][a-z0-9_.-]*$/u;
+const LOCAL_NAME_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+
+function normalizeArchitectureId(value, label) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!ARCHITECTURE_ID_PATTERN.test(normalized)) {
+    throw new TypeError(`${label} must match ${ARCHITECTURE_ID_PATTERN.toString()}.`);
+  }
+  return normalized;
+}
+
+function normalizeCapabilityMap(value, label) {
+  if (value == null) {
+    return Object.freeze({});
+  }
+  if (!isRecord(value)) {
+    throw new TypeError(`${label} must be an object mapping local names to capability ids.`);
+  }
+
+  const normalized = {};
+  const seenCapabilityIds = new Set();
+  for (const [rawLocalName, rawCapabilityId] of Object.entries(value)) {
+    const localName = String(rawLocalName || "").trim();
+    if (!LOCAL_NAME_PATTERN.test(localName)) {
+      throw new TypeError(`${label} local name "${localName}" must be a JavaScript identifier.`);
+    }
+    const capabilityId = normalizeArchitectureId(rawCapabilityId, `${label}.${localName}`);
+    if (seenCapabilityIds.has(capabilityId)) {
+      throw new TypeError(`${label} declares capability "${capabilityId}" more than once.`);
+    }
+    seenCapabilityIds.add(capabilityId);
+    normalized[localName] = capabilityId;
+  }
+
+  return Object.freeze(normalized);
+}
+
+function assertDistinctLocalNames(maps) {
+  const owners = new Map();
+  for (const [kind, entries] of Object.entries(maps)) {
+    for (const localName of Object.keys(entries)) {
+      if (owners.has(localName)) {
+        throw new TypeError(
+          `Provider local name "${localName}" is declared by both ${owners.get(localName)} and ${kind}.`
+        );
+      }
+      owners.set(localName, kind);
+    }
+  }
+}
+
+function normalizeLifecycleMethod(value, label) {
+  if (value == null) {
+    return null;
+  }
+  if (typeof value !== "function") {
+    throw new TypeError(`${label} must be a function when provided.`);
+  }
+  return value;
+}
+
+function defineProvider({
+  id,
+  requires = {},
+  optional = {},
+  provides = {},
+  setup,
+  boot = null,
+  shutdown = null
+} = {}) {
+  const providerId = normalizeArchitectureId(id, "Provider id");
+  const normalizedRequires = normalizeCapabilityMap(requires, `${providerId}.requires`);
+  const normalizedOptional = normalizeCapabilityMap(optional, `${providerId}.optional`);
+  const normalizedProvides = normalizeCapabilityMap(provides, `${providerId}.provides`);
+  assertDistinctLocalNames({
+    requires: normalizedRequires,
+    optional: normalizedOptional,
+    provides: normalizedProvides
+  });
+
+  const setupMethod = normalizeLifecycleMethod(setup, `${providerId}.setup`);
+  if (!setupMethod) {
+    throw new TypeError(`${providerId}.setup is required.`);
+  }
+
+  return Object.freeze({
+    id: providerId,
+    requires: normalizedRequires,
+    optional: normalizedOptional,
+    provides: normalizedProvides,
+    setup: setupMethod,
+    boot: normalizeLifecycleMethod(boot, `${providerId}.boot`),
+    shutdown: normalizeLifecycleMethod(shutdown, `${providerId}.shutdown`)
+  });
+}
+
+export { defineProvider, normalizeArchitectureId };

package/shared/capabilities/index.js

@@ -0,0 +1,2 @@
+export { defineProvider } from "./defineProvider.js";
+export { createCapabilityRuntime } from "./runtime.js";

package/shared/capabilities/runtime.js

@@ -0,0 +1,243 @@
+import { isRecord } from "../support/normalize.js";
+import { defineProvider, normalizeArchitectureId } from "./defineProvider.js";
+
+function normalizeProviderDefinition(value) {
+  if (!isRecord(value)) {
+    throw new TypeError("Capability runtime providers must be provider definitions.");
+  }
+  return defineProvider(value);
+}
+
+function normalizeInputCapabilities(value) {
+  if (value == null) {
+    return new Map();
+  }
+  if (!isRecord(value)) {
+    throw new TypeError("Capability runtime inputs must be an object keyed by capability id.");
+  }
+  return new Map(Object.entries(value).map(([id, capability]) => [
+    normalizeArchitectureId(id, "Runtime input capability id"),
+    capability
+  ]));
+}
+
+function providerCapabilityIds(provider, field) {
+  return Object.values(provider[field] || {});
+}
+
+function buildProviderOrder(providers, inputCapabilities) {
+  const normalizedProviders = providers.map(normalizeProviderDefinition);
+  const providersById = new Map();
+  const providerByCapability = new Map();
+
+  for (const provider of normalizedProviders) {
+    if (providersById.has(provider.id)) {
+      throw new Error(`Provider "${provider.id}" is duplicated.`);
+    }
+    providersById.set(provider.id, provider);
+
+    for (const capabilityId of providerCapabilityIds(provider, "provides")) {
+      if (inputCapabilities.has(capabilityId)) {
+        throw new Error(`Capability "${capabilityId}" is supplied both as a runtime input and by ${provider.id}.`);
+      }
+      if (providerByCapability.has(capabilityId)) {
+        throw new Error(
+          `Capability "${capabilityId}" is provided by both ${providerByCapability.get(capabilityId).id} and ${provider.id}.`
+        );
+      }
+      providerByCapability.set(capabilityId, provider);
+    }
+  }
+
+  for (const provider of normalizedProviders) {
+    for (const capabilityId of providerCapabilityIds(provider, "requires")) {
+      if (!inputCapabilities.has(capabilityId) && !providerByCapability.has(capabilityId)) {
+        throw new Error(`Provider "${provider.id}" requires missing capability "${capabilityId}".`);
+      }
+      if (providerByCapability.get(capabilityId)?.id === provider.id) {
+        throw new Error(`Provider "${provider.id}" cannot require capability "${capabilityId}" that it provides.`);
+      }
+    }
+  }
+
+  const visited = new Set();
+  const visiting = new Set();
+  const ordered = [];
+
+  function visit(provider, lineage = []) {
+    if (visited.has(provider.id)) {
+      return;
+    }
+    if (visiting.has(provider.id)) {
+      throw new Error(`Provider capability cycle detected: ${[...lineage, provider.id].join(" -> ")}.`);
+    }
+
+    visiting.add(provider.id);
+    const dependencyProviders = [
+      ...providerCapabilityIds(provider, "requires"),
+      ...providerCapabilityIds(provider, "optional")
+    ]
+      .map((capabilityId) => providerByCapability.get(capabilityId) || null)
+      .filter(Boolean)
+      .sort((left, right) => left.id.localeCompare(right.id));
+    for (const dependencyProvider of dependencyProviders) {
+      visit(dependencyProvider, [...lineage, provider.id]);
+    }
+    visiting.delete(provider.id);
+    visited.add(provider.id);
+    ordered.push(provider);
+  }
+
+  for (const provider of [...normalizedProviders].sort((left, right) => left.id.localeCompare(right.id))) {
+    visit(provider);
+  }
+  return Object.freeze(ordered);
+}
+
+function resolveProviderDependencies(provider, capabilities) {
+  const dependencies = {};
+  for (const [localName, capabilityId] of Object.entries(provider.requires)) {
+    if (!capabilities.has(capabilityId)) {
+      throw new Error(`Provider "${provider.id}" requires unavailable capability "${capabilityId}".`);
+    }
+    dependencies[localName] = capabilities.get(capabilityId);
+  }
+  for (const [localName, capabilityId] of Object.entries(provider.optional)) {
+    dependencies[localName] = capabilities.has(capabilityId) ? capabilities.get(capabilityId) : null;
+  }
+  return Object.freeze(dependencies);
+}
+
+function normalizeProviderOutputs(provider, value) {
+  const expectedNames = Object.keys(provider.provides);
+  if (expectedNames.length === 0) {
+    if (value != null && (!isRecord(value) || Object.keys(value).length > 0)) {
+      throw new Error(`Provider "${provider.id}" declares no capabilities but setup() returned outputs.`);
+    }
+    return Object.freeze({});
+  }
+  if (!isRecord(value)) {
+    throw new Error(`Provider "${provider.id}" setup() must return its declared capability outputs.`);
+  }
+
+  const actualNames = Object.keys(value).sort();
+  const sortedExpectedNames = [...expectedNames].sort();
+  if (
+    actualNames.length !== sortedExpectedNames.length ||
+    actualNames.some((name, index) => name !== sortedExpectedNames[index])
+  ) {
+    throw new Error(
+      `Provider "${provider.id}" setup() outputs must be exactly: ${sortedExpectedNames.join(", ") || "<none>"}.`
+    );
+  }
+  return Object.freeze({ ...value });
+}
+
+function createCapabilityRuntime({ providers = [], inputs = {}, profile = "" } = {}) {
+  const capabilities = normalizeInputCapabilities(inputs);
+  const providerOrder = buildProviderOrder(Array.isArray(providers) ? providers : [], capabilities);
+  const providerStates = new Map();
+  const normalizedProfile = String(profile || "").trim();
+  let lifecycleState = "created";
+
+  async function stopInitializedProviders() {
+    const stopped = [];
+    let firstError = null;
+    for (const provider of [...providerOrder].reverse()) {
+      if (!providerStates.has(provider.id)) {
+        continue;
+      }
+      if (provider.shutdown) {
+        const state = providerStates.get(provider.id);
+        try {
+          await provider.shutdown(state.dependencies, Object.freeze({
+            outputs: state.outputs,
+            profile: normalizedProfile
+          }));
+        } catch (error) {
+          firstError ||= error;
+        }
+      }
+      stopped.push(provider.id);
+    }
+    if (firstError) {
+      throw firstError;
+    }
+    return Object.freeze(stopped);
+  }
+
+  async function start() {
+    if (lifecycleState !== "created") {
+      throw new Error(`Capability runtime cannot start from state "${lifecycleState}".`);
+    }
+    lifecycleState = "starting";
+
+    try {
+      for (const provider of providerOrder) {
+        const dependencies = resolveProviderDependencies(provider, capabilities);
+        const outputs = normalizeProviderOutputs(
+          provider,
+          await provider.setup(dependencies, Object.freeze({ profile: normalizedProfile }))
+        );
+        for (const [localName, capabilityId] of Object.entries(provider.provides)) {
+          capabilities.set(capabilityId, outputs[localName]);
+        }
+        providerStates.set(provider.id, Object.freeze({ dependencies, outputs }));
+      }
+
+      for (const provider of providerOrder) {
+        if (provider.boot) {
+          const state = providerStates.get(provider.id);
+          await provider.boot(state.dependencies, Object.freeze({
+            outputs: state.outputs,
+            profile: normalizedProfile
+          }));
+        }
+      }
+
+      lifecycleState = "started";
+      return api;
+    } catch (error) {
+      lifecycleState = "failed";
+      try {
+        await stopInitializedProviders();
+      } catch (shutdownError) {
+        throw new AggregateError(
+          [error, shutdownError],
+          "Capability runtime startup failed and cleanup also failed.",
+          { cause: error }
+        );
+      }
+      throw error;
+    }
+  }
+
+  async function shutdown() {
+    if (lifecycleState === "stopped") {
+      return Object.freeze([]);
+    }
+    if (lifecycleState !== "started") {
+      throw new Error(`Capability runtime cannot shut down from state "${lifecycleState}".`);
+    }
+    lifecycleState = "stopping";
+    try {
+      return await stopInitializedProviders();
+    } finally {
+      lifecycleState = "stopped";
+    }
+  }
+
+  function diagnostics() {
+    return Object.freeze({
+      profile: normalizedProfile,
+      lifecycleState,
+      providerOrder: Object.freeze(providerOrder.map((provider) => provider.id)),
+      capabilityIds: Object.freeze([...capabilities.keys()].sort())
+    });
+  }
+
+  const api = Object.freeze({ start, shutdown, diagnostics });
+  return api;
+}
+
+export { createCapabilityRuntime };

package/shared/capabilities/runtime.test.js

@@ -0,0 +1,170 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+
+test("providers receive named required and optional capabilities without a service locator", async () => {
+  const calls = [];
+  const databaseProvider = defineProvider({
+    id: "database.mysql",
+    requires: { env: "runtime.env" },
+    provides: { database: "runtime.database" },
+    setup({ env }) {
+      calls.push(["database", env.DB_NAME]);
+      return { database: Object.freeze({ client: "mysql2" }) };
+    }
+  });
+  const booksProvider = defineProvider({
+    id: "feature.books",
+    requires: { database: "runtime.database" },
+    optional: { logger: "runtime.logger" },
+    provides: { books: "feature.books" },
+    setup({ database, logger }) {
+      calls.push(["books", database.client, logger]);
+      return { books: Object.freeze({ ready: true }) };
+    }
+  });
+
+  const runtime = createCapabilityRuntime({
+    providers: [booksProvider, databaseProvider],
+    inputs: {
+      "runtime.env": { DB_NAME: "catalogue" }
+    }
+  });
+  await runtime.start();
+
+  assert.deepEqual(calls, [
+    ["database", "catalogue"],
+    ["books", "mysql2", null]
+  ]);
+  assert.deepEqual(runtime.diagnostics(), {
+    profile: "",
+    lifecycleState: "started",
+    providerOrder: ["database.mysql", "feature.books"],
+    capabilityIds: ["feature.books", "runtime.database", "runtime.env"]
+  });
+  assert.equal(Object.hasOwn(runtime, "get"), false);
+  assert.equal(Object.hasOwn(runtime, "make"), false);
+  assert.equal(Object.hasOwn(runtime, "has"), false);
+});
+
+test("provider lifecycle receives only declared dependencies and its own outputs", async () => {
+  const calls = [];
+  const provider = defineProvider({
+    id: "feature.lifecycle",
+    provides: { feature: "feature.lifecycle" },
+    setup(dependencies, context) {
+      calls.push(["setup", dependencies, context.profile]);
+      return { feature: { ok: true } };
+    },
+    boot(dependencies, context) {
+      calls.push(["boot", dependencies, context.outputs.feature.ok]);
+    },
+    shutdown(dependencies, context) {
+      calls.push(["shutdown", dependencies, context.outputs.feature.ok]);
+    }
+  });
+  const runtime = createCapabilityRuntime({ providers: [provider], profile: "test" });
+
+  await runtime.start();
+  assert.deepEqual(await runtime.shutdown(), ["feature.lifecycle"]);
+  assert.deepEqual(calls, [
+    ["setup", {}, "test"],
+    ["boot", {}, true],
+    ["shutdown", {}, true]
+  ]);
+});
+
+test("capability runtime rejects missing, duplicate, cyclic, and undeclared capabilities", async () => {
+  assert.throws(
+    () => createCapabilityRuntime({
+      providers: [defineProvider({
+        id: "feature.missing",
+        requires: { database: "runtime.database" },
+        setup() {}
+      })]
+    }),
+    /requires missing capability "runtime\.database"/u
+  );
+
+  const first = defineProvider({
+    id: "feature.first",
+    provides: { value: "feature.value" },
+    setup() {
+      return { value: 1 };
+    }
+  });
+  const second = defineProvider({
+    id: "feature.second",
+    provides: { value: "feature.value" },
+    setup() {
+      return { value: 2 };
+    }
+  });
+  assert.throws(
+    () => createCapabilityRuntime({ providers: [first, second] }),
+    /provided by both feature\.first and feature\.second/u
+  );
+
+  const left = defineProvider({
+    id: "feature.left",
+    requires: { right: "feature.right" },
+    provides: { left: "feature.left" },
+    setup() {
+      return { left: true };
+    }
+  });
+  const right = defineProvider({
+    id: "feature.right",
+    requires: { left: "feature.left" },
+    provides: { right: "feature.right" },
+    setup() {
+      return { right: true };
+    }
+  });
+  assert.throws(
+    () => createCapabilityRuntime({ providers: [left, right] }),
+    /Provider capability cycle detected/u
+  );
+
+  const undeclared = defineProvider({
+    id: "feature.undeclared",
+    provides: { expected: "feature.expected" },
+    setup() {
+      return { expected: true, extra: true };
+    }
+  });
+  const runtime = createCapabilityRuntime({ providers: [undeclared] });
+  await assert.rejects(runtime.start(), /outputs must be exactly: expected/u);
+});
+
+test("failed startup shuts down initialized providers and normal shutdown is idempotent", async () => {
+  const calls = [];
+  const first = defineProvider({
+    id: "feature.first",
+    provides: { first: "feature.first" },
+    setup() {
+      calls.push("first.setup");
+      return { first: true };
+    },
+    shutdown() {
+      calls.push("first.shutdown");
+    }
+  });
+  const failing = defineProvider({
+    id: "feature.failing",
+    requires: { first: "feature.first" },
+    setup() {
+      calls.push("failing.setup");
+      throw new Error("setup failed");
+    }
+  });
+  const failedRuntime = createCapabilityRuntime({ providers: [failing, first] });
+  await assert.rejects(failedRuntime.start(), /setup failed/u);
+  assert.deepEqual(calls, ["first.setup", "failing.setup", "first.shutdown"]);
+  assert.equal(failedRuntime.diagnostics().lifecycleState, "failed");
+
+  const healthyRuntime = createCapabilityRuntime({ providers: [first] });
+  await healthyRuntime.start();
+  assert.deepEqual(await healthyRuntime.shutdown(), ["feature.first"]);
+  assert.deepEqual(await healthyRuntime.shutdown(), []);
+});

package/test/barrelExposure.test.js

@@ -8,17 +8,46 @@ const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
 
 const BARREL_EXPECTATIONS = Object.freeze([
+  Object.freeze({
+    filePath: path.join(REPO_ROOT, "packages", "kernel", "server", "platform", "index.js"),
+    expectedExports: Object.freeze([
+      "createInstalledRuntime",
+      "registerSurfaceRequestConstraint",
+      "resolveRuntimeProfileFromSurface"
+    ])
+  }),
+  Object.freeze({
+    filePath: path.join(REPO_ROOT, "packages", "kernel", "server", "actions", "index.js"),
+    expectedExports: Object.freeze([
+      "createActionCatalogue",
+      "createActionProvider",
+      "createEntityChangedActionEvent"
+    ])
+  }),
+  Object.freeze({
+    filePath: path.join(REPO_ROOT, "packages", "kernel", "shared", "capabilities", "index.js"),
+    expectedExports: Object.freeze([
+      "createCapabilityRuntime",
+      "defineProvider"
+    ])
+  }),
+  Object.freeze({
+    filePath: path.join(REPO_ROOT, "packages", "kernel", "server", "features", "index.js"),
+    expectedExports: Object.freeze([
+      "defineFeature"
+    ])
+  }),
   Object.freeze({
     filePath: path.join(REPO_ROOT, "packages", "kernel", "server", "runtime", "index.js"),
     expectedExports: Object.freeze([
       "AppError",
+      "BootstrapProvider",
+      "EventProvider",
+      "createBootstrapRuntime",
+      "createEventRuntime",
       "createValidationError",
-      "installServiceRegistrationApi",
       "parsePositiveInteger",
-      "requireAuth",
-      "resolveServiceRegistrations",
-      "registerDomainEventListener",
-      "registerBootstrapPayloadContributor"
+      "requireAuth"
     ])
   }),
   Object.freeze({
@@ -40,13 +69,6 @@ const BARREL_EXPECTATIONS = Object.freeze([
       "transientQueryRetryDelay"
     ])
   }),
-  Object.freeze({
-    filePath: path.join(REPO_ROOT, "packages", "kernel", "shared", "actions", "index.js"),
-    expectedExports: Object.freeze([
-      "normalizeActionDefinition",
-      "withActionDefaults"
-    ])
-  }),
   Object.freeze({
     filePath: path.join(REPO_ROOT, "packages", "kernel", "shared", "validators", "index.js"),
     expectedExports: Object.freeze([
@@ -108,7 +130,8 @@ const BARREL_EXPECTATIONS = Object.freeze([
   Object.freeze({
     filePath: path.join(REPO_ROOT, "packages", "kernel", "server", "http", "index.js"),
     expectedExports: Object.freeze([
-      "registerRouteVisibilityResolver"
+      "HttpProvider",
+      "createCapabilityHttpRuntime"
     ])
   })
 ]);

package/test/exportsContract.test.js

@@ -14,7 +14,9 @@ const KERNEL_PACKAGE_JSON_PATH = path.join(
 );
 const SCAN_ROOTS = [
   path.join(REPO_ROOT, "packages"),
-  path.join(REPO_ROOT, "tooling", "create-app", "templates")
+  path.join(REPO_ROOT, "packages", "agent-docs", "patterns", "minimal-foundation", "example"),
+  path.join(REPO_ROOT, "packages", "agent-docs", "patterns", "shell-foundation", "example"),
+  path.join(REPO_ROOT, "packages", "agent-docs", "patterns", "feature-package", "example")
 ];
 const SCANNED_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".vue"]);
 const IGNORED_DIRECTORIES = new Set(["node_modules", ".git", "dist", "coverage"]);
@@ -24,8 +26,11 @@ const EXPORTED_UNUSED_ALLOWLIST = new Set([
   "./_testable",
   // 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",
+  // Public composition-root API. Feature packages normally consume it through
+  // defineFeature(), while infrastructure providers use it directly.
+  "./shared/capabilities",
+  // Public HTTP composition provider used when assembling a server runtime.
+  "./server/http",
   // Public helper API for packages that publish entity-change realtime events.
   "./server/runtime/entityChangeEvents"
 ]);