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

package/dist/index.js

@@ -10,6 +10,89 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// 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) {
@@ -60,7 +143,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 {
@@ -111,40 +196,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
@@ -153,12 +235,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;
     }
   }
   /**
@@ -1011,7 +1097,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);
@@ -1046,7 +1136,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}`;
@@ -1073,7 +1167,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 });
@@ -1152,7 +1250,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);
@@ -1209,7 +1315,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);
@@ -1425,24 +1538,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);
@@ -1601,6 +1702,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);
@@ -1746,13 +1848,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) {
@@ -1762,13 +1921,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);
@@ -1826,35 +1983,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"];
@@ -1920,6 +2055,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);
@@ -2520,6 +2656,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) => {
@@ -4587,14 +4728,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;
   }
@@ -4606,6 +4746,7 @@ function shouldDenyAnonymous(input) {
 }
 
 // src/utils/datetime.ts
+import { nextUtcCalendarDay, utcInstantMs } from "@objectstack/spec/data";
 function calendarPartsInTz(d, tz) {
   const parts = new Intl.DateTimeFormat("en-US", {
     timeZone: tz,
@@ -4846,6 +4987,395 @@ async function bulkWrite(rows, opts) {
   return results;
 }
 
+// src/utils/migration-journal.ts
+import { createHash as createHash2, randomUUID } from "crypto";
+import {
+  MIGRATION_JOURNAL_OBJECT
+} from "@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 createHash2("sha256").update(shape, "utf8").digest("hex").slice(0, 32);
+}
+async function appendEvent(engine, event, execContext) {
+  await engine.insert(
+    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(
+    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(
+    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 ?? 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
 import {
   classifyFilterToken,
@@ -5295,7 +5825,7 @@ var PluginHealthMonitor = class {
 };
 
 // src/hot-reload.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 var generateUUID = () => {
   if (typeof crypto !== "undefined" && crypto.randomUUID) {
     return crypto.randomUUID();
@@ -5390,7 +5920,7 @@ var PluginStateManager = class {
    */
   calculateChecksum(state) {
     const stateStr = JSON.stringify(state);
-    return createHash2("sha256").update(stateStr).digest("hex");
+    return createHash3("sha256").update(stateStr).digest("hex");
   }
   /**
    * Shutdown state manager
@@ -5976,6 +6506,8 @@ export {
   DependencyResolver,
   HotReloadManager,
   LiteKernel,
+  MigrationJournalRefusal,
+  MigrationPlanRegistry,
   NamespaceResolver,
   ObjectKernel,
   ObjectKernelBase,
@@ -5998,6 +6530,7 @@ export {
   ServiceLifecycle,
   UnknownFilterTokenError,
   UnresolvedFilterTokenError,
+  assertInitServiceRequirements,
   bucketKeyToCalendarRange,
   buildPermissionsFromGrants,
   bulkWrite,
@@ -6016,33 +6549,45 @@ export {
   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,