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

package/dist/index.cjs

@@ -40,6 +40,8 @@ __export(index_exports, {
   DependencyResolver: () => DependencyResolver,
   HotReloadManager: () => HotReloadManager,
   LiteKernel: () => LiteKernel,
+  MigrationJournalRefusal: () => MigrationJournalRefusal,
+  MigrationPlanRegistry: () => MigrationPlanRegistry,
   NamespaceResolver: () => NamespaceResolver,
   ObjectKernel: () => ObjectKernel,
   ObjectKernelBase: () => ObjectKernelBase,
@@ -62,6 +64,7 @@ __export(index_exports, {
   ServiceLifecycle: () => ServiceLifecycle,
   UnknownFilterTokenError: () => UnknownFilterTokenError,
   UnresolvedFilterTokenError: () => UnresolvedFilterTokenError,
+  assertInitServiceRequirements: () => assertInitServiceRequirements,
   bucketKeyToCalendarRange: () => bucketKeyToCalendarRange,
   buildPermissionsFromGrants: () => buildPermissionsFromGrants,
   bulkWrite: () => bulkWrite,
@@ -80,33 +83,45 @@ __export(index_exports, {
   deepMerge: () => deepMerge,
   defaultIsTransientError: () => defaultIsTransientError,
   derivePosture: () => derivePosture,
+  describeInitOrderFault: () => describeInitOrderFault,
+  engineCanRollBack: () => engineCanRollBack,
   evaluateAuthGate: () => evaluateAuthGate,
   extractApiKey: () => extractApiKey,
   filterTokenContextFrom: () => filterTokenContextFrom,
+  findInterruptedRuns: () => findInterruptedRuns,
   generateApiKey: () => generateApiKey,
   generateEd25519KeyPair: () => generateEd25519KeyPair,
   getEnv: () => getEnv,
   getMemoryUsage: () => getMemoryUsage,
   hashApiKey: () => hashApiKey,
+  hashMigrationPlan: () => hashMigrationPlan,
   isAuthGateAllowlisted: () => isAuthGateAllowlisted,
   isExpired: () => isExpired,
   isGrantActive: () => isGrantActive,
   isGrantExpired: () => isGrantExpired,
   isNode: () => isNode,
+  nextUtcCalendarDay: () => import_data.nextUtcCalendarDay,
   parseScopes: () => parseScopes,
   parseSignature: () => parseSignature,
+  planChunks: () => planChunks,
   postureVisibleRows: () => postureVisibleRows,
   readAuthoredTranslationLayer: () => readAuthoredTranslationLayer,
+  readRunJournal: () => readRunJournal,
   resolveApiKeyPrincipal: () => resolveApiKeyPrincipal,
   resolveAuthzContext: () => resolveAuthzContext,
   resolveFilterToken: () => resolveFilterToken,
   resolveFilterTokens: () => resolveFilterTokens,
   resolveLocale: () => resolveLocale,
   resolveLocalizationContext: () => resolveLocalizationContext,
+  resolvePluginOrder: () => resolvePluginOrder,
   resolveUserAuthzGrants: () => resolveUserAuthzGrants,
+  resumeMigrationJournal: () => resumeMigrationJournal,
+  runMigrationJournal: () => runMigrationJournal,
   safeExit: () => safeExit,
   shouldDenyAnonymous: () => shouldDenyAnonymous,
   signPayload: () => signPayload,
+  utcInstantMs: () => import_data.utcInstantMs,
+  validateInitServiceContract: () => validateInitServiceContract,
   verifyPayload: () => verifyPayload,
   verifyPlatformSignature: () => verifyPlatformSignature,
   verifyPluginArtifact: () => verifyPluginArtifact,
@@ -117,6 +132,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 +265,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 +318,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 +357,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 +1213,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 +1252,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 +1283,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 +1366,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 +1431,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 +1654,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 +1818,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 +1964,70 @@ 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);
+    assertInitServiceRequirements(plugin, (name) => this.hasAnyService(name));
+    this.currentlyInitializing = plugin.name;
+    try {
+      await this.raceStartupTimeout(
+        plugin.init(this.context),
+        timeout,
+        `Plugin ${plugin.name} init timeout after ${timeout}ms`
+      );
+    } finally {
+      this.currentlyInitializing = void 0;
+    }
+  }
+  /**
+   * Race a plugin lifecycle hook against its startup-timeout guard, and
+   * reclaim the guard the moment the race settles (#4813).
+   *
+   * The guard used to be armed and then abandoned: when the plugin won the
+   * race, its `setTimeout` stayed ref'd in the event loop for the full
+   * `startupTimeout`, so every process idled that long after its work was
+   * done. One `os migrate` finished in 3s and then sat for 120s
+   * (`ObjectQLPlugin.startupTimeout`), held open by 8 orphaned guards — one
+   * per init plus one per start.
+   *
+   * Clearing on settle rather than `unref()`-ing at arm time is deliberate.
+   * An unref'd guard also stops pinning the loop, but it stops being a guard
+   * as well: if the hook never settles and nothing else keeps the loop alive,
+   * Node exits before the timer can fire and the timeout is never reported.
+   * The guard has to stay ref'd exactly as long as the race is undecided,
+   * which is what `clearTimeout` in a `finally` expresses.
+   *
+   * `operation` is widened to `T | PromiseLike<T>` because the Plugin
+   * contract permits a synchronous hook (`init`/`start` return
+   * `void | Promise<void>`); such a hook wins the race immediately and the
+   * guard is reclaimed on the same turn.
+   */
+  async raceStartupTimeout(operation, timeout, message) {
+    let guard;
     const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => {
-        reject(new Error(`Plugin ${plugin.name} init timeout after ${timeout}ms`));
+      guard = setTimeout(() => {
+        reject(new Error(message));
       }, timeout);
     });
-    await Promise.race([initPromise, timeoutPromise]);
+    try {
+      return await Promise.race([operation, timeoutPromise]);
+    } finally {
+      clearTimeout(guard);
+    }
+  }
+  /**
+   * 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) {
@@ -1863,13 +2037,11 @@ var ObjectKernel = class {
     const startTime = Date.now();
     this.logger.debug(`Start: ${plugin.name}`, { plugin: plugin.name });
     try {
-      const startPromise = plugin.start(this.context);
-      const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => {
-          reject(new Error(`Plugin ${plugin.name} start timeout after ${timeout}ms`));
-        }, timeout);
-      });
-      await Promise.race([startPromise, timeoutPromise]);
+      await this.raceStartupTimeout(
+        plugin.start(this.context),
+        timeout,
+        `Plugin ${plugin.name} start timeout after ${timeout}ms`
+      );
       const duration = Date.now() - startTime;
       this.startedPlugins.add(plugin.name);
       this.pluginStartTimes.set(plugin.name, duration);
@@ -1927,35 +2099,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 +2171,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 +2772,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 +4839,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 +4857,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,
@@ -4942,8 +5098,395 @@ async function bulkWrite(rows, opts) {
   return results;
 }
 
+// src/utils/migration-journal.ts
+var import_node_crypto3 = require("crypto");
+var import_system3 = require("@objectstack/spec/system");
+var SYSTEM_CTX = { isSystem: true };
+var DEFAULT_CHUNK_SIZE = 200;
+function engineCanRollBack(engine) {
+  const e = engine;
+  if (typeof e?.transaction !== "function") return false;
+  const defaultDriverName = e.getDefaultDriverName?.();
+  const defaultDriver = defaultDriverName ? e.getDriverByName?.(defaultDriverName) : void 0;
+  return !defaultDriver || typeof defaultDriver.beginTransaction === "function";
+}
+var MigrationPlanRegistry = class {
+  constructor() {
+    this.plans = /* @__PURE__ */ new Map();
+  }
+  register(plan) {
+    this.plans.set(plan.id, plan);
+  }
+  get(planId) {
+    return this.plans.get(planId);
+  }
+  list() {
+    return [...this.plans.values()];
+  }
+};
+var MigrationJournalRefusal = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "MigrationJournalRefusal";
+    this.code = code;
+  }
+};
+function planChunks(plan, rowCounts, chunkSize = plan.chunkSize ?? DEFAULT_CHUNK_SIZE) {
+  const size = Math.max(1, chunkSize);
+  const chunks = [];
+  plan.steps.forEach((step, stepIndex) => {
+    const total = rowCounts[stepIndex] ?? 0;
+    for (let offset = 0; offset < total; offset += size) {
+      chunks.push({
+        index: chunks.length,
+        stepIndex,
+        stepName: step.name,
+        offset,
+        length: Math.min(size, total - offset)
+      });
+    }
+  });
+  return chunks;
+}
+function hashMigrationPlan(plan, chunks) {
+  const shape = JSON.stringify({
+    id: plan.id,
+    steps: plan.steps.map((s) => s.name),
+    chunks: chunks.map((c) => [c.stepIndex, c.offset, c.length])
+  });
+  return (0, import_node_crypto3.createHash)("sha256").update(shape, "utf8").digest("hex").slice(0, 32);
+}
+async function appendEvent(engine, event, execContext) {
+  await engine.insert(
+    import_system3.MIGRATION_JOURNAL_OBJECT,
+    { ...event, created_at: event.created_at ?? (/* @__PURE__ */ new Date()).toISOString() },
+    { context: execContext ?? { ...SYSTEM_CTX } }
+  );
+}
+async function readRunJournal(engine, runId) {
+  const rows = await engine.find(
+    import_system3.MIGRATION_JOURNAL_OBJECT,
+    { where: { run_id: runId } },
+    { context: { ...SYSTEM_CTX } }
+  );
+  return [...rows ?? []].sort((a, b) => Number(a.seq) - Number(b.seq));
+}
+function chunkSetOf(events, kind) {
+  const out = /* @__PURE__ */ new Set();
+  for (const e of events) {
+    if (e.kind === kind && typeof e.chunk_index === "number") out.add(e.chunk_index);
+  }
+  return out;
+}
+async function findInterruptedRuns(engine) {
+  const started = await engine.find(
+    import_system3.MIGRATION_JOURNAL_OBJECT,
+    { where: { kind: "run_started" } },
+    { context: { ...SYSTEM_CTX } }
+  );
+  const out = [];
+  for (const start of started ?? []) {
+    const events = await readRunJournal(engine, start.run_id);
+    if (events.some((e) => e.kind === "run_done")) continue;
+    const committed = chunkSetOf(events, "chunk_done");
+    const compensated = chunkSetOf(events, "compensated");
+    const outstanding = [...committed].filter((i) => !compensated.has(i));
+    if (events.some((e) => e.kind === "run_failed") && outstanding.length === 0) continue;
+    const unknown = [...chunkSetOf(events, "chunk_started")].filter((i) => !committed.has(i));
+    let planId = start.run_id;
+    try {
+      planId = start.detail ? JSON.parse(start.detail).planId ?? start.run_id : start.run_id;
+    } catch {
+    }
+    out.push({
+      runId: start.run_id,
+      planId,
+      planHash: start.plan_hash ?? "",
+      migrationId: start.migration_id,
+      startedAt: start.created_at,
+      committedChunks: [...committed].sort((a, b) => a - b),
+      unknownChunks: unknown.sort((a, b) => a - b),
+      compensatedChunks: [...compensated].sort((a, b) => a - b)
+    });
+  }
+  return out;
+}
+async function loadPlan(engine, plan, chunkSize) {
+  const rowsByStep = [];
+  for (const step of plan.steps) rowsByStep.push(await step.load(engine) ?? []);
+  const chunks = planChunks(plan, rowsByStep.map((r) => r.length), chunkSize ?? plan.chunkSize);
+  return { chunks, planHash: hashMigrationPlan(plan, chunks), rowsByStep };
+}
+async function runMigrationJournal(engine, plan, options = {}) {
+  const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  if (!engineCanRollBack(engine)) {
+    throw new MigrationJournalRefusal(
+      "NOT_IMPLEMENTED",
+      `Migration plan '${plan.id}' requires engine transaction support; this runtime cannot roll back. The journal's chunk_done markers would not mean "committed", so the run is refused rather than started.`
+    );
+  }
+  const { chunks, planHash, rowsByStep } = await loadPlan(engine, plan, options.chunkSize);
+  const resuming = Boolean(options.runId);
+  const runId = options.runId ?? (0, import_node_crypto3.randomUUID)();
+  let events = [];
+  let seq = 0;
+  let committed = /* @__PURE__ */ new Set();
+  let compensated = /* @__PURE__ */ new Set();
+  const attemptsByChunk = /* @__PURE__ */ new Map();
+  if (resuming) {
+    events = await readRunJournal(engine, runId);
+    if (events.length === 0) {
+      throw new MigrationJournalRefusal("NO_SUCH_RUN", `No journal rows for run '${runId}'.`);
+    }
+    const start = events.find((e) => e.kind === "run_started");
+    if (start?.plan_hash && start.plan_hash !== planHash) {
+      throw new MigrationJournalRefusal(
+        "PLAN_CHANGED",
+        `Refusing to resume run '${runId}': plan hash ${planHash} does not match the journal's ${start.plan_hash}. The chunk boundaries recorded in the journal describe a different plan.`
+      );
+    }
+    if (events.some((e) => e.kind === "run_done")) {
+      return {
+        runId,
+        status: "completed",
+        chunksTotal: chunks.length,
+        chunksCommitted: chunkSetOf(events, "chunk_done").size,
+        chunksCompensated: chunkSetOf(events, "compensated").size,
+        planHash
+      };
+    }
+    seq = events.reduce((m, e) => Math.max(m, Number(e.seq) + 1), 0);
+    committed = chunkSetOf(events, "chunk_done");
+    compensated = chunkSetOf(events, "compensated");
+    for (const e of events) {
+      if (e.kind === "chunk_started" && typeof e.chunk_index === "number") {
+        attemptsByChunk.set(e.chunk_index, (attemptsByChunk.get(e.chunk_index) ?? 0) + 1);
+      }
+    }
+  }
+  for (const step of plan.steps) {
+    if (!step.preflight) continue;
+    try {
+      await step.preflight(engine);
+    } catch (err) {
+      throw new MigrationJournalRefusal(
+        "PREFLIGHT_FAILED",
+        `Migration plan '${plan.id}' refused: preflight for step '${step.name}' failed: ${errText(err)}`
+      );
+    }
+  }
+  if (plan.onCrash === "compensate") {
+    const missing = plan.steps.filter((s) => !s.compensate).map((s) => s.name);
+    if (missing.length > 0) {
+      throw new MigrationJournalRefusal(
+        "NOT_COMPENSABLE",
+        `Migration plan '${plan.id}' declares onCrash: 'compensate' but step(s) ${missing.join(", ")} declare no compensate().`
+      );
+    }
+  }
+  const rowsOf = (c) => rowsByStep[c.stepIndex].slice(c.offset, c.offset + c.length);
+  const next = () => seq++;
+  if (!resuming) {
+    await appendEvent(engine, {
+      run_id: runId,
+      seq: next(),
+      kind: "run_started",
+      plan_hash: planHash,
+      migration_id: plan.migrationId,
+      created_at: now(),
+      detail: JSON.stringify({
+        planId: plan.id,
+        onCrash: plan.onCrash ?? "resume",
+        chunks: chunks.map((c) => ({ i: c.index, step: c.stepName, offset: c.offset, length: c.length }))
+      })
+    });
+  }
+  if (resuming && plan.onCrash === "compensate") {
+    return await unwind(engine, plan, {
+      runId,
+      planHash,
+      chunks,
+      rowsOf,
+      next,
+      now,
+      committed,
+      compensated,
+      chunksTotal: chunks.length,
+      cause: new Error(`run '${runId}' rediscovered after interruption; plan policy is compensate`)
+    });
+  }
+  for (const chunk of chunks) {
+    if (committed.has(chunk.index)) continue;
+    const attempt = (attemptsByChunk.get(chunk.index) ?? 0) + 1;
+    attemptsByChunk.set(chunk.index, attempt);
+    const step = plan.steps[chunk.stepIndex];
+    const rows = rowsOf(chunk);
+    await appendEvent(engine, {
+      run_id: runId,
+      seq: next(),
+      kind: "chunk_started",
+      chunk_index: chunk.index,
+      attempt,
+      migration_id: plan.migrationId,
+      created_at: now()
+    });
+    try {
+      await engine.transaction(async (trxCtx) => {
+        await step.forward(rows, { runId, chunkIndex: chunk.index, attempt, context: trxCtx }, engine);
+        await appendEvent(
+          engine,
+          {
+            run_id: runId,
+            seq: next(),
+            kind: "chunk_done",
+            chunk_index: chunk.index,
+            attempt,
+            migration_id: plan.migrationId,
+            created_at: now()
+          },
+          trxCtx
+        );
+      }, { ...SYSTEM_CTX });
+      committed.add(chunk.index);
+    } catch (err) {
+      return await unwind(engine, plan, {
+        runId,
+        planHash,
+        chunks,
+        rowsOf,
+        next,
+        now,
+        committed,
+        compensated,
+        chunksTotal: chunks.length,
+        cause: err
+      });
+    }
+  }
+  await appendEvent(engine, {
+    run_id: runId,
+    seq: next(),
+    kind: "run_done",
+    migration_id: plan.migrationId,
+    created_at: now()
+  });
+  return {
+    runId,
+    status: "completed",
+    chunksTotal: chunks.length,
+    chunksCommitted: committed.size,
+    chunksCompensated: compensated.size,
+    planHash
+  };
+}
+async function unwind(engine, plan, a) {
+  const order = [...a.committed].sort((x, y) => y - x);
+  for (const index of order) {
+    if (a.compensated.has(index)) continue;
+    const chunk = a.chunks[index];
+    const step = plan.steps[chunk.stepIndex];
+    if (!step.compensate) {
+      await appendEvent(engine, {
+        run_id: a.runId,
+        seq: a.next(),
+        kind: "run_failed",
+        chunk_index: index,
+        migration_id: plan.migrationId,
+        created_at: a.now(),
+        detail: JSON.stringify({
+          phase: "compensate",
+          reason: "step declares no compensate()",
+          step: step.name,
+          cause: errText(a.cause)
+        })
+      });
+      return {
+        runId: a.runId,
+        status: "failed",
+        chunksTotal: a.chunksTotal,
+        chunksCommitted: a.committed.size,
+        chunksCompensated: a.compensated.size,
+        planHash: a.planHash,
+        error: a.cause
+      };
+    }
+    const attempt = 1;
+    try {
+      await engine.transaction(async (trxCtx) => {
+        await step.compensate(a.rowsOf(chunk), { runId: a.runId, chunkIndex: index, attempt, context: trxCtx }, engine);
+        await appendEvent(
+          engine,
+          {
+            run_id: a.runId,
+            seq: a.next(),
+            kind: "compensated",
+            chunk_index: index,
+            attempt,
+            migration_id: plan.migrationId,
+            created_at: a.now()
+          },
+          trxCtx
+        );
+      }, { ...SYSTEM_CTX });
+      a.compensated.add(index);
+    } catch (err) {
+      await appendEvent(engine, {
+        run_id: a.runId,
+        seq: a.next(),
+        kind: "run_failed",
+        chunk_index: index,
+        migration_id: plan.migrationId,
+        created_at: a.now(),
+        detail: JSON.stringify({
+          phase: "compensate",
+          step: step.name,
+          error: errText(err),
+          cause: errText(a.cause)
+        })
+      });
+      return {
+        runId: a.runId,
+        status: "failed",
+        chunksTotal: a.chunksTotal,
+        chunksCommitted: a.committed.size,
+        chunksCompensated: a.compensated.size,
+        planHash: a.planHash,
+        error: err
+      };
+    }
+  }
+  await appendEvent(engine, {
+    run_id: a.runId,
+    seq: a.next(),
+    kind: "run_failed",
+    migration_id: plan.migrationId,
+    created_at: a.now(),
+    detail: JSON.stringify({ phase: "forward", error: errText(a.cause), compensated: [...a.compensated].sort((x, y) => x - y) })
+  });
+  return {
+    runId: a.runId,
+    status: "compensated",
+    chunksTotal: a.chunksTotal,
+    chunksCommitted: a.committed.size,
+    chunksCompensated: a.compensated.size,
+    planHash: a.planHash,
+    error: a.cause
+  };
+}
+async function resumeMigrationJournal(engine, plan, runId, options = {}) {
+  return runMigrationJournal(engine, plan, { ...options, runId });
+}
+function errText(err) {
+  if (err instanceof Error) return err.message;
+  try {
+    return String(err);
+  } catch {
+    return "<unprintable error>";
+  }
+}
+
 // 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 +5637,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 +5648,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 +5661,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);
@@ -5388,7 +5931,7 @@ var PluginHealthMonitor = class {
 };
 
 // src/hot-reload.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto4 = require("crypto");
 var generateUUID = () => {
   if (typeof crypto !== "undefined" && crypto.randomUUID) {
     return crypto.randomUUID();
@@ -5483,7 +6026,7 @@ var PluginStateManager = class {
    */
   calculateChecksum(state) {
     const stateStr = JSON.stringify(state);
-    return (0, import_node_crypto3.createHash)("sha256").update(stateStr).digest("hex");
+    return (0, import_node_crypto4.createHash)("sha256").update(stateStr).digest("hex");
   }
   /**
    * Shutdown state manager
@@ -6070,6 +6613,8 @@ var NamespaceResolver = class {
   DependencyResolver,
   HotReloadManager,
   LiteKernel,
+  MigrationJournalRefusal,
+  MigrationPlanRegistry,
   NamespaceResolver,
   ObjectKernel,
   ObjectKernelBase,
@@ -6092,6 +6637,7 @@ var NamespaceResolver = class {
   ServiceLifecycle,
   UnknownFilterTokenError,
   UnresolvedFilterTokenError,
+  assertInitServiceRequirements,
   bucketKeyToCalendarRange,
   buildPermissionsFromGrants,
   bulkWrite,
@@ -6110,33 +6656,45 @@ var NamespaceResolver = class {
   deepMerge,
   defaultIsTransientError,
   derivePosture,
+  describeInitOrderFault,
+  engineCanRollBack,
   evaluateAuthGate,
   extractApiKey,
   filterTokenContextFrom,
+  findInterruptedRuns,
   generateApiKey,
   generateEd25519KeyPair,
   getEnv,
   getMemoryUsage,
   hashApiKey,
+  hashMigrationPlan,
   isAuthGateAllowlisted,
   isExpired,
   isGrantActive,
   isGrantExpired,
   isNode,
+  nextUtcCalendarDay,
   parseScopes,
   parseSignature,
+  planChunks,
   postureVisibleRows,
   readAuthoredTranslationLayer,
+  readRunJournal,
   resolveApiKeyPrincipal,
   resolveAuthzContext,
   resolveFilterToken,
   resolveFilterTokens,
   resolveLocale,
   resolveLocalizationContext,
+  resolvePluginOrder,
   resolveUserAuthzGrants,
+  resumeMigrationJournal,
+  runMigrationJournal,
   safeExit,
   shouldDenyAnonymous,
   signPayload,
+  utcInstantMs,
+  validateInitServiceContract,
   verifyPayload,
   verifyPlatformSignature,
   verifyPluginArtifact,