@objectstack/core 17.0.0-rc.0 → 17.0.0-rc.1

package/dist/index.cjs

@@ -62,6 +62,7 @@ __export(index_exports, {
   ServiceLifecycle: () => ServiceLifecycle,
   UnknownFilterTokenError: () => UnknownFilterTokenError,
   UnresolvedFilterTokenError: () => UnresolvedFilterTokenError,
+  assertInitServiceRequirements: () => assertInitServiceRequirements,
   bucketKeyToCalendarRange: () => bucketKeyToCalendarRange,
   buildPermissionsFromGrants: () => buildPermissionsFromGrants,
   bulkWrite: () => bulkWrite,
@@ -80,6 +81,7 @@ __export(index_exports, {
   deepMerge: () => deepMerge,
   defaultIsTransientError: () => defaultIsTransientError,
   derivePosture: () => derivePosture,
+  describeInitOrderFault: () => describeInitOrderFault,
   evaluateAuthGate: () => evaluateAuthGate,
   extractApiKey: () => extractApiKey,
   filterTokenContextFrom: () => filterTokenContextFrom,
@@ -93,6 +95,7 @@ __export(index_exports, {
   isGrantActive: () => isGrantActive,
   isGrantExpired: () => isGrantExpired,
   isNode: () => isNode,
+  nextUtcCalendarDay: () => import_data.nextUtcCalendarDay,
   parseScopes: () => parseScopes,
   parseSignature: () => parseSignature,
   postureVisibleRows: () => postureVisibleRows,
@@ -103,10 +106,13 @@ __export(index_exports, {
   resolveFilterTokens: () => resolveFilterTokens,
   resolveLocale: () => resolveLocale,
   resolveLocalizationContext: () => resolveLocalizationContext,
+  resolvePluginOrder: () => resolvePluginOrder,
   resolveUserAuthzGrants: () => resolveUserAuthzGrants,
   safeExit: () => safeExit,
   shouldDenyAnonymous: () => shouldDenyAnonymous,
   signPayload: () => signPayload,
+  utcInstantMs: () => import_data.utcInstantMs,
+  validateInitServiceContract: () => validateInitServiceContract,
   verifyPayload: () => verifyPayload,
   verifyPlatformSignature: () => verifyPlatformSignature,
   verifyPluginArtifact: () => verifyPluginArtifact,
@@ -117,6 +123,89 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/plugin-order.ts
+function resolvePluginOrder(plugins) {
+  const resolved = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const visit = (pluginName) => {
+    if (visited.has(pluginName)) return;
+    if (visiting.has(pluginName)) {
+      throw new Error(`[Kernel] Circular dependency detected: ${pluginName}`);
+    }
+    const plugin = plugins.get(pluginName);
+    if (!plugin) {
+      throw new Error(`[Kernel] Plugin '${pluginName}' not found`);
+    }
+    visiting.add(pluginName);
+    for (const dep of plugin.dependencies ?? []) {
+      if (!plugins.has(dep)) {
+        throw new Error(
+          `[Kernel] Dependency '${dep}' not found for plugin '${pluginName}'`
+        );
+      }
+      visit(dep);
+    }
+    for (const dep of plugin.optionalDependencies ?? []) {
+      if (plugins.has(dep)) visit(dep);
+    }
+    visiting.delete(pluginName);
+    visited.add(pluginName);
+    resolved.push(plugin);
+  };
+  for (const pluginName of plugins.keys()) {
+    visit(pluginName);
+  }
+  return resolved;
+}
+function validateInitServiceContract(ordered, isServiceRegistered) {
+  const providerSlot = /* @__PURE__ */ new Map();
+  ordered.forEach((plugin, slot) => {
+    for (const service of plugin.providesServices ?? []) {
+      if (!providerSlot.has(service)) {
+        providerSlot.set(service, { plugin: plugin.name, slot });
+      }
+    }
+  });
+  const violations = [];
+  ordered.forEach((plugin, slot) => {
+    for (const service of plugin.requiresServices ?? []) {
+      if (isServiceRegistered(service)) continue;
+      const provider = providerSlot.get(service);
+      if (provider && provider.slot > slot) {
+        violations.push(
+          `'${plugin.name}' requires service '${service}' during init, but '${service}' is provided by '${provider.plugin}', which initializes later (slot ${provider.slot} vs ${slot}). Registration order is not a contract \u2014 declare '${provider.plugin}' in '${plugin.name}'.dependencies (hard) or .optionalDependencies (order-if-present) so the kernel hoists it.`
+        );
+      }
+    }
+  });
+  if (violations.length > 0) {
+    throw new Error(
+      `[Kernel] Plugin ordering contract violated (#4131):
+  - ${violations.join("\n  - ")}`
+    );
+  }
+}
+function describeInitOrderFault(currentlyInitializing, plugins, serviceName) {
+  if (!currentlyInitializing) return "";
+  let providerHint = "";
+  for (const plugin of plugins) {
+    if (plugin.providesServices?.includes(serviceName)) {
+      providerHint = ` '${serviceName}' is provided by composed plugin '${plugin.name}', which has not initialized yet \u2014 declare it in the requiring plugin's dependencies/optionalDependencies.`;
+      break;
+    }
+  }
+  return ` (while plugin '${currentlyInitializing}' was initializing \u2014 a composition/ordering fault, #4131.${providerHint})`;
+}
+function assertInitServiceRequirements(plugin, isServiceRegistered) {
+  for (const service of plugin.requiresServices ?? []) {
+    if (isServiceRegistered(service)) continue;
+    throw new Error(
+      `[Kernel] Plugin '${plugin.name}' requires service '${service}' at init, but no such service is registered at this point of the boot. No composed plugin that initializes earlier provides it \u2014 compose a provider (and, if it initializes later without declaring '${service}' in providesServices, order it ahead via this plugin's dependencies/optionalDependencies) (#4131).`
+    );
+  }
+}
+
 // src/kernel-base.ts
 var ObjectKernelBase = class {
   constructor(logger) {
@@ -167,7 +256,9 @@ var ObjectKernelBase = class {
         if (this.services instanceof Map) {
           const service = this.services.get(name);
           if (!service) {
-            throw new Error(`[Kernel] Service '${name}' not found`);
+            throw new Error(
+              `[Kernel] Service '${name}' not found${this.describeInitOrderFault(name)}`
+            );
           }
           return service;
         } else {
@@ -218,40 +309,37 @@ var ObjectKernelBase = class {
     };
   }
   /**
-   * Resolve plugin dependencies using topological sort
+   * Resolve plugin dependencies using topological sort — `dependencies`
+   * hard, `optionalDependencies` order-if-present (ADR-0116, #4131). One
+   * implementation shared with ObjectKernel via `plugin-order.ts`.
    * @returns Ordered list of plugins (dependencies first)
    */
   resolveDependencies() {
-    const resolved = [];
-    const visited = /* @__PURE__ */ new Set();
-    const visiting = /* @__PURE__ */ new Set();
-    const visit = (pluginName) => {
-      if (visited.has(pluginName)) return;
-      if (visiting.has(pluginName)) {
-        throw new Error(`[Kernel] Circular dependency detected: ${pluginName}`);
-      }
-      const plugin = this.plugins.get(pluginName);
-      if (!plugin) {
-        throw new Error(`[Kernel] Plugin '${pluginName}' not found`);
-      }
-      visiting.add(pluginName);
-      const deps = plugin.dependencies || [];
-      for (const dep of deps) {
-        if (!this.plugins.has(dep)) {
-          throw new Error(
-            `[Kernel] Dependency '${dep}' not found for plugin '${pluginName}'`
-          );
-        }
-        visit(dep);
-      }
-      visiting.delete(pluginName);
-      visited.add(pluginName);
-      resolved.push(plugin);
-    };
-    for (const pluginName of this.plugins.keys()) {
-      visit(pluginName);
-    }
-    return resolved;
+    return resolvePluginOrder(this.plugins);
+  }
+  /**
+   * Whether a service is registered on this kernel right now. Backs the
+   * init-service contract checks (#4131).
+   */
+  hasRegisteredService(name) {
+    return this.services.has(name);
+  }
+  /**
+   * Pre-Phase-1 ordering validation (ADR-0116, #4131): a plugin whose
+   * `requiresServices` names a service provided only by a LATER plugin is
+   * a named boot error before any init side effects.
+   */
+  validateInitServices(ordered) {
+    validateInitServiceContract(ordered, (name) => this.hasRegisteredService(name));
+  }
+  /**
+   * When a getService miss happens while a plugin's init() is running,
+   * append the structural diagnosis (#4131): which plugin was initializing,
+   * and — when a composed plugin declares the service — who provides it.
+   * Empty string outside Phase 1, so non-boot messages stay unchanged.
+   */
+  describeInitOrderFault(serviceName) {
+    return describeInitOrderFault(this.currentlyInitializing, this.plugins.values(), serviceName);
   }
   /**
    * Run plugin init phase
@@ -260,12 +348,16 @@ var ObjectKernelBase = class {
   async runPluginInit(plugin) {
     const pluginName = plugin.name;
     this.logger.info(`Initializing plugin: ${pluginName}`);
+    assertInitServiceRequirements(plugin, (name) => this.hasRegisteredService(name));
+    this.currentlyInitializing = pluginName;
     try {
       await plugin.init(this.context);
       this.logger.info(`Plugin initialized: ${pluginName}`);
     } catch (error) {
       this.logger.error(`Plugin init failed: ${pluginName}`, error);
       throw error;
+    } finally {
+      this.currentlyInitializing = void 0;
     }
   }
   /**
@@ -1112,7 +1204,11 @@ function createMemoryCache() {
   let hits = 0;
   let misses = 0;
   return {
-    _fallback: true,
+    __serviceInfo: {
+      status: "degraded",
+      handlerReady: false,
+      message: "In-process Map cache \u2014 not shared across instances, lost on restart. Register a cache plugin (e.g. Redis) for a real one."
+    },
     _serviceName: "cache",
     async get(key) {
       const entry = store.get(key);
@@ -1147,7 +1243,11 @@ function createMemoryQueue() {
   const handlers = /* @__PURE__ */ new Map();
   let msgId = 0;
   return {
-    _fallback: true,
+    __serviceInfo: {
+      status: "degraded",
+      handlerReady: false,
+      message: "Synchronous in-process delivery \u2014 no durability, retry, or cross-instance fan-out. Register a queue plugin (e.g. BullMQ) for a real one."
+    },
     _serviceName: "queue",
     async publish(queue, data) {
       const id = `fallback-msg-${++msgId}`;
@@ -1174,7 +1274,11 @@ function createMemoryQueue() {
 function createMemoryJob() {
   const jobs = /* @__PURE__ */ new Map();
   return {
-    _fallback: true,
+    __serviceInfo: {
+      status: "degraded",
+      handlerReady: false,
+      message: "In-process job registry \u2014 trigger() runs handlers, but scheduled jobs never fire on their own (no timer). Register a job plugin (e.g. Agenda) for real scheduling."
+    },
     _serviceName: "job",
     async schedule(name, schedule, handler) {
       jobs.set(name, { schedule, handler });
@@ -1253,7 +1357,15 @@ function createMemoryI18n() {
     return void 0;
   }
   return {
-    _fallback: true,
+    // [#4058] `degraded` (ADR-0076 D12): translations, locale fallback and
+    // interpolation are all real — what is missing is persistence and the
+    // authoring surface service-i18n adds. `handlerReady` left at the
+    // `degraded` default (true): the dispatcher's `/i18n` domain does serve
+    // this implementation.
+    __serviceInfo: {
+      status: "degraded",
+      message: "In-memory translations \u2014 real lookup and locale fallback, but nothing is persisted. Register I18nServicePlugin from @objectstack/service-i18n for the full implementation."
+    },
     _serviceName: "i18n",
     t(key, locale, params) {
       const data = resolveTranslations(locale) ?? mergedLocale(defaultLocale);
@@ -1310,7 +1422,14 @@ function createMemoryMetadata() {
     return map;
   }
   return {
-    _fallback: true,
+    // [#4058] `degraded` (ADR-0076 D12): the registry is real — everything
+    // registered is listable and readable back — it simply never reaches disk
+    // or a database. `handlerReady` keeps the `degraded` default (true): the
+    // dispatcher's `/meta` domain serves this implementation.
+    __serviceInfo: {
+      status: "degraded",
+      message: "In-memory metadata registry \u2014 real reads and writes, no persistence (lost on restart). Register MetadataPlugin for a persisted registry."
+    },
     _serviceName: "metadata",
     async register(type, name, data) {
       getTypeMap(type).set(name, data);
@@ -1526,24 +1645,12 @@ var ObjectKernel = class {
           this.services.set(name, loaderService);
           return loaderService;
         }
-        try {
-          const service2 = this.pluginLoader.getService(name);
-          if (service2 instanceof Promise) {
-            service2.catch(() => {
-            });
-            throw new Error(`Service '${name}' is async - use await`);
-          }
-          return service2;
-        } catch (error) {
-          if (error.message?.includes("is async")) {
-            throw error;
-          }
-          const isNotFoundError = error.message === `Service '${name}' not found`;
-          if (!isNotFoundError) {
-            throw error;
-          }
-          throw new Error(`[Kernel] Service '${name}' not found`);
+        if (!this.pluginLoader.hasService(name)) {
+          throw new Error(
+            `[Kernel] Service '${name}' not found${this.describeInitOrderFault(name)}`
+          );
         }
+        throw new Error(`Service '${name}' is async - use await`);
       },
       replaceService: (name, implementation) => {
         const hasService = this.services.has(name) || this.pluginLoader.hasService(name);
@@ -1702,6 +1809,7 @@ var ObjectKernel = class {
         this.logger.warn("Circular service dependencies detected:", { cycles });
       }
       const orderedPlugins = this.resolveDependencies();
+      validateInitServiceContract(orderedPlugins, (name) => this.hasAnyService(name));
       this.logger.info("Phase 1: Init plugins");
       for (const plugin of orderedPlugins) {
         await this.initPluginWithTimeout(plugin);
@@ -1847,13 +1955,36 @@ var ObjectKernel = class {
   async initPluginWithTimeout(plugin) {
     const timeout = plugin.startupTimeout || this.config.defaultStartupTimeout;
     this.logger.debug(`Init: ${plugin.name}`, { plugin: plugin.name });
-    const initPromise = plugin.init(this.context);
-    const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => {
-        reject(new Error(`Plugin ${plugin.name} init timeout after ${timeout}ms`));
-      }, timeout);
-    });
-    await Promise.race([initPromise, timeoutPromise]);
+    assertInitServiceRequirements(plugin, (name) => this.hasAnyService(name));
+    this.currentlyInitializing = plugin.name;
+    try {
+      const initPromise = plugin.init(this.context);
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`Plugin ${plugin.name} init timeout after ${timeout}ms`));
+        }, timeout);
+      });
+      await Promise.race([initPromise, timeoutPromise]);
+    } finally {
+      this.currentlyInitializing = void 0;
+    }
+  }
+  /**
+   * Whether a service is resolvable on this kernel right now — direct
+   * registration or a loader-registered factory. Backs the init-service
+   * contract checks (#4131).
+   */
+  hasAnyService(name) {
+    return this.services.has(name) || this.pluginLoader.hasService(name);
+  }
+  /**
+   * When a getService miss happens while a plugin's init() is running,
+   * append the structural diagnosis (#4131): which plugin was initializing,
+   * and — when a composed plugin declares the service — who provides it.
+   * Empty string outside Phase 1, so non-boot messages stay unchanged.
+   */
+  describeInitOrderFault(serviceName) {
+    return describeInitOrderFault(this.currentlyInitializing, this.plugins.values(), serviceName);
   }
   async startPluginWithTimeout(plugin) {
     if (!plugin.start) {
@@ -1927,35 +2058,13 @@ var ObjectKernel = class {
       }
     }
   }
+  /**
+   * Topological order over `dependencies` (hard) + `optionalDependencies`
+   * (order-if-present) — ADR-0116, #4131. One implementation shared with
+   * LiteKernel via `plugin-order.ts`.
+   */
   resolveDependencies() {
-    const resolved = [];
-    const visited = /* @__PURE__ */ new Set();
-    const visiting = /* @__PURE__ */ new Set();
-    const visit = (pluginName) => {
-      if (visited.has(pluginName)) return;
-      if (visiting.has(pluginName)) {
-        throw new Error(`[Kernel] Circular dependency detected: ${pluginName}`);
-      }
-      const plugin = this.plugins.get(pluginName);
-      if (!plugin) {
-        throw new Error(`[Kernel] Plugin '${pluginName}' not found`);
-      }
-      visiting.add(pluginName);
-      const deps = plugin.dependencies || [];
-      for (const dep of deps) {
-        if (!this.plugins.has(dep)) {
-          throw new Error(`[Kernel] Dependency '${dep}' not found for plugin '${pluginName}'`);
-        }
-        visit(dep);
-      }
-      visiting.delete(pluginName);
-      visited.add(pluginName);
-      resolved.push(plugin);
-    };
-    for (const pluginName of this.plugins.keys()) {
-      visit(pluginName);
-    }
-    return resolved;
+    return resolvePluginOrder(this.plugins);
   }
   registerShutdownSignals() {
     const signals = ["SIGINT", "SIGTERM", "SIGQUIT"];
@@ -2021,6 +2130,7 @@ var LiteKernel = class extends ObjectKernelBase {
     this.state = "initializing";
     this.logger.info("Bootstrap started");
     const orderedPlugins = this.resolveDependencies();
+    this.validateInitServices(orderedPlugins);
     this.logger.info("Phase 1: Init plugins");
     for (const plugin of orderedPlugins) {
       await this.runPluginInit(plugin);
@@ -2621,6 +2731,11 @@ function createApiRegistryPlugin(config = {}) {
   } = config;
   return {
     name: "com.objectstack.core.api-registry",
+    /**
+     * Services init() registers on every path (ADR-0116, #4131) — lets the
+     * kernel name this plugin when a consumer requires one before it inits.
+     */
+    providesServices: ["api-registry"],
     type: "standard",
     version: "1.0.0",
     init: async (ctx) => {
@@ -4683,14 +4798,13 @@ function evaluateAuthGate(sessionUser, path) {
 
 // src/security/anonymous-deny.ts
 var ANONYMOUS_DENY_STATUS = 401;
-var ANONYMOUS_DENY_CODE = "unauthenticated";
+var ANONYMOUS_DENY_CODE = "UNAUTHENTICATED";
 var ANONYMOUS_DENY_MESSAGE = "Authentication is required to access this endpoint.";
 var ANONYMOUS_DENY_BODY = {
   error: ANONYMOUS_DENY_CODE,
   message: ANONYMOUS_DENY_MESSAGE
 };
 function shouldDenyAnonymous(input) {
-  if (!input.requireAuth) return false;
   if (typeof input.method === "string" && input.method.toUpperCase() === "OPTIONS") {
     return false;
   }
@@ -4702,6 +4816,7 @@ function shouldDenyAnonymous(input) {
 }
 
 // src/utils/datetime.ts
+var import_data = require("@objectstack/spec/data");
 function calendarPartsInTz(d, tz) {
   const parts = new Intl.DateTimeFormat("en-US", {
     timeZone: tz,
@@ -4943,7 +5058,7 @@ async function bulkWrite(rows, opts) {
 }
 
 // src/utils/filter-tokens.ts
-var import_data = require("@objectstack/spec/data");
+var import_data2 = require("@objectstack/spec/data");
 var UnknownFilterTokenError = class extends Error {
   constructor(token, suggestion) {
     super(
@@ -5094,7 +5209,7 @@ function resolveFilterToken(token, ctx = {}) {
   }
   const period = resolvePeriodToken(token, today);
   if (period !== void 0) return period;
-  const param = (0, import_data.parseDateMacroParam)(token);
+  const param = (0, import_data2.parseDateMacroParam)(token);
   if (param) {
     const sign = param.direction === "ago" ? -1 : 1;
     if (param.unit === "minute" || param.unit === "hour") {
@@ -5105,7 +5220,7 @@ function resolveFilterToken(token, ctx = {}) {
   return void 0;
 }
 function hasFilterToken(node) {
-  if (typeof node === "string") return (0, import_data.classifyFilterToken)(node) !== null;
+  if (typeof node === "string") return (0, import_data2.classifyFilterToken)(node) !== null;
   if (Array.isArray(node)) return node.some(hasFilterToken);
   if (node && typeof node === "object" && !(node instanceof Date)) {
     return Object.values(node).some(hasFilterToken);
@@ -5118,7 +5233,7 @@ function resolveFilterTokens(filter, ctx = {}) {
   const pinned = { ...ctx, now: ctx.now ?? /* @__PURE__ */ new Date() };
   const walk = (node) => {
     if (typeof node === "string") {
-      const cls = (0, import_data.classifyFilterToken)(node);
+      const cls = (0, import_data2.classifyFilterToken)(node);
       if (!cls) return node;
       if (cls.kind === "unknown") throw new UnknownFilterTokenError(cls.token, cls.suggestion);
       const resolved = resolveFilterToken(cls.token, pinned);
@@ -6092,6 +6207,7 @@ var NamespaceResolver = class {
   ServiceLifecycle,
   UnknownFilterTokenError,
   UnresolvedFilterTokenError,
+  assertInitServiceRequirements,
   bucketKeyToCalendarRange,
   buildPermissionsFromGrants,
   bulkWrite,
@@ -6110,6 +6226,7 @@ var NamespaceResolver = class {
   deepMerge,
   defaultIsTransientError,
   derivePosture,
+  describeInitOrderFault,
   evaluateAuthGate,
   extractApiKey,
   filterTokenContextFrom,
@@ -6123,6 +6240,7 @@ var NamespaceResolver = class {
   isGrantActive,
   isGrantExpired,
   isNode,
+  nextUtcCalendarDay,
   parseScopes,
   parseSignature,
   postureVisibleRows,
@@ -6133,10 +6251,13 @@ var NamespaceResolver = class {
   resolveFilterTokens,
   resolveLocale,
   resolveLocalizationContext,
+  resolvePluginOrder,
   resolveUserAuthzGrants,
   safeExit,
   shouldDenyAnonymous,
   signPayload,
+  utcInstantMs,
+  validateInitServiceContract,
   verifyPayload,
   verifyPlatformSignature,
   verifyPluginArtifact,