@h-rig/kernel-seed 0.0.6-alpha.133

package/README.md

@@ -0,0 +1 @@
+# @h-rig/kernel-seed

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./pluginAbi";
+export * from "./resolveCapability";
+export * from "./seed";

package/dist/src/index.js

@@ -0,0 +1,165 @@
+// @bun
+// packages/kernel-seed/src/pluginAbi.ts
+function loadedPluginId(plugin) {
+  return plugin.meta.id;
+}
+// packages/kernel-seed/src/resolveCapability.ts
+class AmbiguousCapabilityError extends Error {
+  capability;
+  providers;
+  name = "AmbiguousCapabilityError";
+  constructor(capability, providers) {
+    super(`Ambiguous capability provider for ${capability}: ${providers.join(", ")}`);
+    this.capability = capability;
+    this.providers = providers;
+  }
+}
+
+class CapabilityProviderMissingError extends Error {
+  capability;
+  name = "CapabilityProviderMissingError";
+  constructor(capability) {
+    super(`No provider resolved for capability ${capability}`);
+    this.capability = capability;
+  }
+}
+function capabilityValue(plugin, capability) {
+  const direct = plugin.runtime.capabilities?.[capability];
+  const value = direct ?? (capability === "kernel" ? plugin.runtime.kernel : undefined) ?? plugin.runtime;
+  return value;
+}
+function replacementTarget(capability, providerId) {
+  return `${capability}@${providerId}`;
+}
+function capabilityProviders(plugins, capability) {
+  return plugins.filter((plugin) => plugin.provides.has(capability));
+}
+function byPrecedence(providers, precedence) {
+  if (!precedence || precedence.length === 0)
+    return null;
+  const byId = new Map(providers.map((provider) => [loadedPluginId(provider), provider]));
+  for (const id of precedence) {
+    const provider = byId.get(id);
+    if (provider)
+      return provider;
+  }
+  return null;
+}
+function providersAfterReplacement(capability, providers) {
+  const providerIds = new Set(providers.map(loadedPluginId));
+  const replaced = new Set;
+  for (const provider of providers) {
+    for (const replacement of provider.replaces ?? []) {
+      const separator = replacement.indexOf("@");
+      if (separator <= 0)
+        continue;
+      const replacementCapability = replacement.slice(0, separator);
+      const replacementProviderId = replacement.slice(separator + 1);
+      if (replacementCapability === capability && providerIds.has(replacementProviderId)) {
+        replaced.add(replacementProviderId);
+      }
+    }
+  }
+  return {
+    providers: providers.filter((provider) => !replaced.has(loadedPluginId(provider))),
+    replaced: [...replaced].sort()
+  };
+}
+function resolveCapability(plugins, capability, config = {}) {
+  const providers = capabilityProviders(plugins, capability);
+  if (providers.length === 0)
+    return null;
+  const precedenceProvider = byPrecedence(providers, config.capabilityPrecedence?.[capability]);
+  if (precedenceProvider) {
+    return {
+      capability,
+      plugin: precedenceProvider,
+      value: capabilityValue(precedenceProvider, capability),
+      selectedBy: "precedence",
+      replacedProviders: []
+    };
+  }
+  const afterReplacement = providersAfterReplacement(capability, providers);
+  if (afterReplacement.providers.length === 1) {
+    const [provider] = afterReplacement.providers;
+    if (!provider)
+      throw new CapabilityProviderMissingError(capability);
+    return {
+      capability,
+      plugin: provider,
+      value: capabilityValue(provider, capability),
+      selectedBy: afterReplacement.replaced.length > 0 ? "replaces" : "sole-provider",
+      replacedProviders: afterReplacement.replaced
+    };
+  }
+  throw new AmbiguousCapabilityError(capability, afterReplacement.providers.map(loadedPluginId).sort());
+}
+function declaresReplacement(plugin, capability, providerId) {
+  return (plugin.replaces ?? []).includes(replacementTarget(capability, providerId));
+}
+// packages/kernel-seed/src/seed.ts
+class BootIncoherent extends Error {
+  name = "BootIncoherent";
+  constructor(message) {
+    super(message);
+  }
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object";
+}
+function objectAt(value, key) {
+  const child = value[key];
+  return isRecord(child) ? child : null;
+}
+function hasFunction(value, key) {
+  return value !== null && typeof value[key] === "function";
+}
+function assertSatisfiesKernelInterface(value) {
+  if (!isRecord(value)) {
+    throw new BootIncoherent("kernel provider did not return an object");
+  }
+  const stageRunner = objectAt(value, "stageRunner");
+  if (!hasFunction(stageRunner, "resolve") || !hasFunction(stageRunner, "runPipeline")) {
+    throw new BootIncoherent("kernel provider must expose stageRunner.resolve and stageRunner.runPipeline");
+  }
+  const journal = objectAt(value, "journal");
+  if (!hasFunction(journal, "append") || !hasFunction(journal, "recordPipeline") || !hasFunction(journal, "read")) {
+    throw new BootIncoherent("kernel provider must expose journal.append, journal.recordPipeline, and journal.read");
+  }
+  const loaderPolicy = objectAt(value, "loaderPolicy");
+  if (!hasFunction(loaderPolicy, "resolveCapability")) {
+    throw new BootIncoherent("kernel provider must expose loaderPolicy.resolveCapability");
+  }
+  const transport = objectAt(value, "transport");
+  if (!hasFunction(transport, "dispatch")) {
+    throw new BootIncoherent("kernel provider must expose transport.dispatch");
+  }
+  if (typeof value.start !== "function") {
+    throw new BootIncoherent("kernel provider must expose start");
+  }
+}
+async function loadPlugins(config) {
+  if (config.loadPlugins) {
+    return await config.loadPlugins();
+  }
+  return config.plugins ?? [];
+}
+async function boot(config) {
+  const plugins = await loadPlugins(config);
+  const resolution = resolveCapability(plugins, "kernel", config);
+  if (!resolution) {
+    throw new BootIncoherent("no kernel provider resolved");
+  }
+  assertSatisfiesKernelInterface(resolution.value);
+  return { kernel: resolution.value, plugins };
+}
+export {
+  resolveCapability,
+  loadedPluginId,
+  declaresReplacement,
+  boot,
+  assertSatisfiesKernelInterface,
+  CapabilityProviderMissingError,
+  BootIncoherent,
+  AmbiguousCapabilityError
+};

package/dist/src/pluginAbi.d.ts

@@ -0,0 +1,31 @@
+import type { CapabilityTag, KernelCapability } from "@rig/contracts";
+export type PluginMeta = {
+    readonly id: string;
+    readonly name?: string;
+    readonly version?: string;
+};
+export type CapabilityReplacement = `${CapabilityTag}@${string}`;
+export type PluginContributions = Readonly<Record<string, unknown>>;
+export type PluginRuntimeChannel = {
+    readonly capabilities?: Readonly<Record<string, unknown>>;
+    readonly kernel?: KernelCapability;
+};
+export type LoadedPlugin = {
+    readonly meta: PluginMeta;
+    readonly provides: ReadonlySet<CapabilityTag>;
+    readonly requires?: readonly CapabilityTag[];
+    readonly replaces?: readonly CapabilityReplacement[];
+    readonly contributes: PluginContributions;
+    readonly runtime: PluginRuntimeChannel;
+};
+export type CapabilityPrecedence = Partial<Record<CapabilityTag, readonly string[]>>;
+export type ResolvedBootConfig = {
+    readonly plugins?: readonly LoadedPlugin[];
+    readonly loadPlugins?: () => Promise<readonly LoadedPlugin[]> | readonly LoadedPlugin[];
+    readonly capabilityPrecedence?: CapabilityPrecedence;
+};
+export type BootResult = {
+    readonly kernel: KernelCapability;
+    readonly plugins: readonly LoadedPlugin[];
+};
+export declare function loadedPluginId(plugin: LoadedPlugin): string;

package/dist/src/pluginAbi.js

@@ -0,0 +1,8 @@
+// @bun
+// packages/kernel-seed/src/pluginAbi.ts
+function loadedPluginId(plugin) {
+  return plugin.meta.id;
+}
+export {
+  loadedPluginId
+};

package/dist/src/resolveCapability.d.ts

@@ -0,0 +1,24 @@
+import type { CapabilityTag } from "@rig/contracts";
+import type { CapabilityPrecedence, LoadedPlugin } from "./pluginAbi";
+export type CapabilityResolution<T> = {
+    readonly capability: CapabilityTag;
+    readonly plugin: LoadedPlugin;
+    readonly value: T;
+    readonly selectedBy: "sole-provider" | "precedence" | "replaces";
+    readonly replacedProviders: readonly string[];
+};
+export declare class AmbiguousCapabilityError extends Error {
+    readonly capability: CapabilityTag;
+    readonly providers: readonly string[];
+    readonly name = "AmbiguousCapabilityError";
+    constructor(capability: CapabilityTag, providers: readonly string[]);
+}
+export declare class CapabilityProviderMissingError extends Error {
+    readonly capability: CapabilityTag;
+    readonly name = "CapabilityProviderMissingError";
+    constructor(capability: CapabilityTag);
+}
+export declare function resolveCapability<T>(plugins: readonly LoadedPlugin[], capability: CapabilityTag, config?: {
+    readonly capabilityPrecedence?: CapabilityPrecedence;
+}): CapabilityResolution<T> | null;
+export declare function declaresReplacement(plugin: LoadedPlugin, capability: CapabilityTag, providerId: string): boolean;

package/dist/src/resolveCapability.js

@@ -0,0 +1,106 @@
+// @bun
+// packages/kernel-seed/src/pluginAbi.ts
+function loadedPluginId(plugin) {
+  return plugin.meta.id;
+}
+
+// packages/kernel-seed/src/resolveCapability.ts
+class AmbiguousCapabilityError extends Error {
+  capability;
+  providers;
+  name = "AmbiguousCapabilityError";
+  constructor(capability, providers) {
+    super(`Ambiguous capability provider for ${capability}: ${providers.join(", ")}`);
+    this.capability = capability;
+    this.providers = providers;
+  }
+}
+
+class CapabilityProviderMissingError extends Error {
+  capability;
+  name = "CapabilityProviderMissingError";
+  constructor(capability) {
+    super(`No provider resolved for capability ${capability}`);
+    this.capability = capability;
+  }
+}
+function capabilityValue(plugin, capability) {
+  const direct = plugin.runtime.capabilities?.[capability];
+  const value = direct ?? (capability === "kernel" ? plugin.runtime.kernel : undefined) ?? plugin.runtime;
+  return value;
+}
+function replacementTarget(capability, providerId) {
+  return `${capability}@${providerId}`;
+}
+function capabilityProviders(plugins, capability) {
+  return plugins.filter((plugin) => plugin.provides.has(capability));
+}
+function byPrecedence(providers, precedence) {
+  if (!precedence || precedence.length === 0)
+    return null;
+  const byId = new Map(providers.map((provider) => [loadedPluginId(provider), provider]));
+  for (const id of precedence) {
+    const provider = byId.get(id);
+    if (provider)
+      return provider;
+  }
+  return null;
+}
+function providersAfterReplacement(capability, providers) {
+  const providerIds = new Set(providers.map(loadedPluginId));
+  const replaced = new Set;
+  for (const provider of providers) {
+    for (const replacement of provider.replaces ?? []) {
+      const separator = replacement.indexOf("@");
+      if (separator <= 0)
+        continue;
+      const replacementCapability = replacement.slice(0, separator);
+      const replacementProviderId = replacement.slice(separator + 1);
+      if (replacementCapability === capability && providerIds.has(replacementProviderId)) {
+        replaced.add(replacementProviderId);
+      }
+    }
+  }
+  return {
+    providers: providers.filter((provider) => !replaced.has(loadedPluginId(provider))),
+    replaced: [...replaced].sort()
+  };
+}
+function resolveCapability(plugins, capability, config = {}) {
+  const providers = capabilityProviders(plugins, capability);
+  if (providers.length === 0)
+    return null;
+  const precedenceProvider = byPrecedence(providers, config.capabilityPrecedence?.[capability]);
+  if (precedenceProvider) {
+    return {
+      capability,
+      plugin: precedenceProvider,
+      value: capabilityValue(precedenceProvider, capability),
+      selectedBy: "precedence",
+      replacedProviders: []
+    };
+  }
+  const afterReplacement = providersAfterReplacement(capability, providers);
+  if (afterReplacement.providers.length === 1) {
+    const [provider] = afterReplacement.providers;
+    if (!provider)
+      throw new CapabilityProviderMissingError(capability);
+    return {
+      capability,
+      plugin: provider,
+      value: capabilityValue(provider, capability),
+      selectedBy: afterReplacement.replaced.length > 0 ? "replaces" : "sole-provider",
+      replacedProviders: afterReplacement.replaced
+    };
+  }
+  throw new AmbiguousCapabilityError(capability, afterReplacement.providers.map(loadedPluginId).sort());
+}
+function declaresReplacement(plugin, capability, providerId) {
+  return (plugin.replaces ?? []).includes(replacementTarget(capability, providerId));
+}
+export {
+  resolveCapability,
+  declaresReplacement,
+  CapabilityProviderMissingError,
+  AmbiguousCapabilityError
+};

package/dist/src/seed.d.ts

@@ -0,0 +1,8 @@
+import type { KernelCapability } from "@rig/contracts";
+import type { BootResult, ResolvedBootConfig } from "./pluginAbi";
+export declare class BootIncoherent extends Error {
+    readonly name = "BootIncoherent";
+    constructor(message: string);
+}
+export declare function assertSatisfiesKernelInterface(value: unknown): asserts value is KernelCapability;
+export declare function boot(config: ResolvedBootConfig): Promise<BootResult>;

package/dist/src/seed.js

@@ -0,0 +1,156 @@
+// @bun
+// packages/kernel-seed/src/pluginAbi.ts
+function loadedPluginId(plugin) {
+  return plugin.meta.id;
+}
+
+// packages/kernel-seed/src/resolveCapability.ts
+class AmbiguousCapabilityError extends Error {
+  capability;
+  providers;
+  name = "AmbiguousCapabilityError";
+  constructor(capability, providers) {
+    super(`Ambiguous capability provider for ${capability}: ${providers.join(", ")}`);
+    this.capability = capability;
+    this.providers = providers;
+  }
+}
+
+class CapabilityProviderMissingError extends Error {
+  capability;
+  name = "CapabilityProviderMissingError";
+  constructor(capability) {
+    super(`No provider resolved for capability ${capability}`);
+    this.capability = capability;
+  }
+}
+function capabilityValue(plugin, capability) {
+  const direct = plugin.runtime.capabilities?.[capability];
+  const value = direct ?? (capability === "kernel" ? plugin.runtime.kernel : undefined) ?? plugin.runtime;
+  return value;
+}
+function capabilityProviders(plugins, capability) {
+  return plugins.filter((plugin) => plugin.provides.has(capability));
+}
+function byPrecedence(providers, precedence) {
+  if (!precedence || precedence.length === 0)
+    return null;
+  const byId = new Map(providers.map((provider) => [loadedPluginId(provider), provider]));
+  for (const id of precedence) {
+    const provider = byId.get(id);
+    if (provider)
+      return provider;
+  }
+  return null;
+}
+function providersAfterReplacement(capability, providers) {
+  const providerIds = new Set(providers.map(loadedPluginId));
+  const replaced = new Set;
+  for (const provider of providers) {
+    for (const replacement of provider.replaces ?? []) {
+      const separator = replacement.indexOf("@");
+      if (separator <= 0)
+        continue;
+      const replacementCapability = replacement.slice(0, separator);
+      const replacementProviderId = replacement.slice(separator + 1);
+      if (replacementCapability === capability && providerIds.has(replacementProviderId)) {
+        replaced.add(replacementProviderId);
+      }
+    }
+  }
+  return {
+    providers: providers.filter((provider) => !replaced.has(loadedPluginId(provider))),
+    replaced: [...replaced].sort()
+  };
+}
+function resolveCapability(plugins, capability, config = {}) {
+  const providers = capabilityProviders(plugins, capability);
+  if (providers.length === 0)
+    return null;
+  const precedenceProvider = byPrecedence(providers, config.capabilityPrecedence?.[capability]);
+  if (precedenceProvider) {
+    return {
+      capability,
+      plugin: precedenceProvider,
+      value: capabilityValue(precedenceProvider, capability),
+      selectedBy: "precedence",
+      replacedProviders: []
+    };
+  }
+  const afterReplacement = providersAfterReplacement(capability, providers);
+  if (afterReplacement.providers.length === 1) {
+    const [provider] = afterReplacement.providers;
+    if (!provider)
+      throw new CapabilityProviderMissingError(capability);
+    return {
+      capability,
+      plugin: provider,
+      value: capabilityValue(provider, capability),
+      selectedBy: afterReplacement.replaced.length > 0 ? "replaces" : "sole-provider",
+      replacedProviders: afterReplacement.replaced
+    };
+  }
+  throw new AmbiguousCapabilityError(capability, afterReplacement.providers.map(loadedPluginId).sort());
+}
+
+// packages/kernel-seed/src/seed.ts
+class BootIncoherent extends Error {
+  name = "BootIncoherent";
+  constructor(message) {
+    super(message);
+  }
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object";
+}
+function objectAt(value, key) {
+  const child = value[key];
+  return isRecord(child) ? child : null;
+}
+function hasFunction(value, key) {
+  return value !== null && typeof value[key] === "function";
+}
+function assertSatisfiesKernelInterface(value) {
+  if (!isRecord(value)) {
+    throw new BootIncoherent("kernel provider did not return an object");
+  }
+  const stageRunner = objectAt(value, "stageRunner");
+  if (!hasFunction(stageRunner, "resolve") || !hasFunction(stageRunner, "runPipeline")) {
+    throw new BootIncoherent("kernel provider must expose stageRunner.resolve and stageRunner.runPipeline");
+  }
+  const journal = objectAt(value, "journal");
+  if (!hasFunction(journal, "append") || !hasFunction(journal, "recordPipeline") || !hasFunction(journal, "read")) {
+    throw new BootIncoherent("kernel provider must expose journal.append, journal.recordPipeline, and journal.read");
+  }
+  const loaderPolicy = objectAt(value, "loaderPolicy");
+  if (!hasFunction(loaderPolicy, "resolveCapability")) {
+    throw new BootIncoherent("kernel provider must expose loaderPolicy.resolveCapability");
+  }
+  const transport = objectAt(value, "transport");
+  if (!hasFunction(transport, "dispatch")) {
+    throw new BootIncoherent("kernel provider must expose transport.dispatch");
+  }
+  if (typeof value.start !== "function") {
+    throw new BootIncoherent("kernel provider must expose start");
+  }
+}
+async function loadPlugins(config) {
+  if (config.loadPlugins) {
+    return await config.loadPlugins();
+  }
+  return config.plugins ?? [];
+}
+async function boot(config) {
+  const plugins = await loadPlugins(config);
+  const resolution = resolveCapability(plugins, "kernel", config);
+  if (!resolution) {
+    throw new BootIncoherent("no kernel provider resolved");
+  }
+  assertSatisfiesKernelInterface(resolution.value);
+  return { kernel: resolution.value, plugins };
+}
+export {
+  boot,
+  assertSatisfiesKernelInterface,
+  BootIncoherent
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@h-rig/kernel-seed",
+  "version": "0.0.6-alpha.133",
+  "type": "module",
+  "description": "Irreducible Rig bootstrap seed, plugin ABI, and capability resolver.",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./resolve-capability": {
+      "types": "./dist/src/resolveCapability.d.ts",
+      "import": "./dist/src/resolveCapability.js"
+    },
+    "./seed": {
+      "types": "./dist/src/seed.d.ts",
+      "import": "./dist/src/seed.js"
+    },
+    "./plugin-abi": {
+      "types": "./dist/src/pluginAbi.d.ts",
+      "import": "./dist/src/pluginAbi.js"
+    }
+  },
+  "engines": {
+    "bun": ">=1.3.11"
+  },
+  "main": "./dist/src/index.js",
+  "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "dependencies": {
+    "@rig/contracts": "npm:@h-rig/contracts@0.0.6-alpha.133"
+  }
+}