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

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { Logger, IServiceRegistry } from '@objectstack/spec/contracts';
-export { IDataDriver, IDataEngine, IHttpRequest, IHttpResponse, IHttpServer, Logger, Middleware, RouteHandler } from '@objectstack/spec/contracts';
+import { Logger, LifecycleEventName, IServiceRegistry, IObjectQLEngine } from '@objectstack/spec/contracts';
+export { EngineSchemaRegistryView, IDataDriver, IDataEngine, IHttpRequest, IHttpResponse, IHttpServer, IObjectQLEngine, Logger, Middleware, RouteHandler } from '@objectstack/spec/contracts';
 import { z } from 'zod';
-import { LoggerConfig } from '@objectstack/spec/system';
+import { LoggerConfig, MigrationOnCrashPolicy, MigrationJournalEvent } from '@objectstack/spec/system';
 import { ObjectLogger } from './logger.cjs';
 export { createLogger } from './logger.cjs';
 import { ConflictResolutionStrategy, ApiRegistryEntryInput, ApiRegistryEntry, ApiDiscoveryQuery, ApiDiscoveryResponse, ApiEndpointRegistration, ApiRegistry as ApiRegistry$1 } from '@objectstack/spec/api';
@@ -9,6 +9,7 @@ import * as QA from '@objectstack/spec/qa';
 import { KeyObject } from 'node:crypto';
 import { PluginCapability, PluginPermissions as PluginPermissions$1, PluginPermissionSet, ResourceType, PermissionAction, PluginPermission, SandboxConfig, KernelSecurityScanResult, KernelSecurityVulnerability, PluginHealthCheck, PluginHealthStatus as PluginHealthStatus$1, PluginHealthReport, HotReloadConfig, VersionConstraint, DependencyConflict, SemanticVersion, CompatibilityLevel } from '@objectstack/spec/kernel';
 import { AuthzPosture } from '@objectstack/spec/security';
+export { nextUtcCalendarDay, utcInstantMs } from '@objectstack/spec/data';
 
 /**
  * Service Lifecycle Types
@@ -213,6 +214,12 @@ declare class ObjectKernel {
     private startedPlugins;
     private pluginStartTimes;
     private shutdownHandlers;
+    /**
+     * Name of the plugin whose init() is currently executing (Phase 1 is
+     * sequential, so at most one). Lets a getService miss during init name
+     * the structural fault (#4131) instead of only the symptom.
+     */
+    private currentlyInitializing?;
     constructor(config?: ObjectKernelConfig);
     /**
      * Register a plugin with enhanced validation
@@ -290,9 +297,51 @@ declare class ObjectKernel {
      */
     getState(): string;
     private initPluginWithTimeout;
+    /**
+     * 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.
+     */
+    private raceStartupTimeout;
+    /**
+     * Whether a service is resolvable on this kernel right now — direct
+     * registration or a loader-registered factory. Backs the init-service
+     * contract checks (#4131).
+     */
+    private hasAnyService;
+    /**
+     * 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.
+     */
+    private describeInitOrderFault;
     private startPluginWithTimeout;
     private rollbackStartedPlugins;
     private performShutdown;
+    /**
+     * Topological order over `dependencies` (hard) + `optionalDependencies`
+     * (order-if-present) — ADR-0116, #4131. One implementation shared with
+     * LiteKernel via `plugin-order.ts`.
+     */
     private resolveDependencies;
     private registerShutdownSignals;
     /**
@@ -350,17 +399,22 @@ interface PluginContext {
      */
     getServices(): Map<string, any>;
     /**
-     * Register a hook handler
+     * Register a hook handler.
+     *
+     * Known lifecycle-bus names (see `IPluginLifecycleEvents` in
+     * `@objectstack/spec`) autocomplete; the bus stays open to custom
+     * cross-plugin event names, so any string remains valid.
+     *
      * @param name - Hook name (e.g., 'kernel:ready', 'data:beforeInsert')
      * @param handler - Hook handler function
      */
-    hook(name: string, handler: (...args: any[]) => void | Promise<void>): void;
+    hook(name: LifecycleEventName | (string & {}), handler: (...args: any[]) => void | Promise<void>): void;
     /**
      * Trigger a hook
-     * @param name - Hook name
+     * @param name - Hook name (known lifecycle names autocomplete; custom names stay legal)
      * @param args - Arguments to pass to hook handlers
      */
-    trigger(name: string, ...args: any[]): Promise<void>;
+    trigger(name: LifecycleEventName | (string & {}), ...args: any[]): Promise<void>;
     /**
      * Logger instance
      */
@@ -393,8 +447,35 @@ interface Plugin {
     /**
      * List of other plugin names that this plugin depends on.
      * The kernel ensures these plugins are initialized before this one.
+     * A name that is not registered on the kernel is a boot error.
      */
     dependencies?: string[];
+    /**
+     * Soft dependencies — order-if-present (ADR-0116, #4131).
+     * Registered names are hoisted ahead exactly like `dependencies`;
+     * absent names are silently skipped instead of failing the boot.
+     * For plugins that DEGRADE gracefully without the dependency but must
+     * never initialize before it when both are composed (e.g. AppPlugin on
+     * an engine-less metadata-only kernel).
+     */
+    optionalDependencies?: string[];
+    /**
+     * Services this plugin resolves SYNCHRONOUSLY during `init()`
+     * (ADR-0116, #4131). The kernel validates the resolved order before
+     * Phase 1 (a required service whose only declared provider initializes
+     * later is a named boot error) and re-checks immediately before this
+     * plugin's init runs. Declare only hard init-time needs — a service the
+     * init merely probes behind a try/catch does not belong here.
+     */
+    requiresServices?: string[];
+    /**
+     * Services this plugin's `init()` UNCONDITIONALLY registers
+     * (ADR-0116, #4131). Powers the pre-Phase-1 ordering validation and
+     * lets misordering errors name the provider. Never declare a service
+     * that is registered conditionally (option-gated, environment-gated):
+     * the kernel would blame orderings this plugin cannot satisfy.
+     */
+    providesServices?: string[];
     /**
      * Init Phase: Register services
      * Called when kernel is initializing.
@@ -437,6 +518,12 @@ declare abstract class ObjectKernelBase {
     protected state: KernelState;
     protected logger: Logger;
     protected context: PluginContext;
+    /**
+     * Name of the plugin whose init() is currently executing (Phase 1 runs
+     * sequentially, so there is at most one). Lets a getService miss during
+     * init name the structural fault (#4131) instead of only the symptom.
+     */
+    protected currentlyInitializing?: string;
     constructor(logger: Logger);
     /**
      * Validate kernel state
@@ -454,10 +541,30 @@ declare abstract class ObjectKernelBase {
      */
     protected createContext(): PluginContext;
     /**
-     * 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)
      */
     protected resolveDependencies(): Plugin[];
+    /**
+     * Whether a service is registered on this kernel right now. Backs the
+     * init-service contract checks (#4131).
+     */
+    protected hasRegisteredService(name: string): boolean;
+    /**
+     * 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.
+     */
+    protected validateInitServices(ordered: Plugin[]): void;
+    /**
+     * 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.
+     */
+    protected describeInitOrderFault(serviceName: string): string;
     /**
      * Run plugin init phase
      * @param plugin - Plugin to initialize
@@ -495,6 +602,100 @@ declare abstract class ObjectKernelBase {
     abstract destroy(): Promise<void>;
 }
 
+/**
+ * Plugin ordering + init-service contract (ADR-0116, #4131).
+ *
+ * The kernel resolves BOTH init and start order from the plugin dependency
+ * graph, so `kernel.use()` registration order proves nothing. Twice a plugin
+ * relied on list position anyway and shipped a boot that dies inside init —
+ * the first cut of DefaultDatasourcePlugin (started after boot schema-sync;
+ * server with no tables) and AppPlugin (#4085: `manifest` grabbed in init
+ * before ObjectQLPlugin registered it). Both times the fix existed only as a
+ * convention: put the plugin in the right slot, write a comment. This module
+ * is the enforced form of that contract, shared by ObjectKernel and
+ * LiteKernel so there is exactly one ordering semantic:
+ *
+ *  - `dependencies` — hard: hoisted ahead, missing ⇒ boot error (unchanged).
+ *  - `optionalDependencies` — order-if-present: hoisted ahead when composed,
+ *    silently skipped when absent. For plugins that DEGRADE without the
+ *    dependency but must never init before it (AppPlugin on an engine-less
+ *    metadata-only kernel).
+ *  - `requiresServices` — services a plugin resolves SYNCHRONOUSLY during
+ *    `init()`. Validated before Phase 1 (provable misordering ⇒ named error
+ *    instead of a crash inside init) and again immediately before each init
+ *    (authoritative: the service is either registered by now or init dies).
+ *  - `providesServices` — services a plugin's `init()` UNCONDITIONALLY
+ *    registers. Powers the pre-Phase-1 check and the named diagnostics.
+ *    Declare only unconditional registrations: a conditional service (e.g.
+ *    one gated behind an option) would indict this plugin for orderings it
+ *    cannot actually satisfy.
+ *
+ * Declaring is NOT voluntary (#4471). Everything above can only enforce what
+ * a plugin declares — a plugin that resolves `getService('X')` during init()
+ * and declares nothing was invisible to all of it, failing only under
+ * unlucky composition orders (#4085, and #4420 at data-consistency cost).
+ * `scripts/check-init-service-contract.mjs` (CI: `check:init-service-contract`)
+ * closes that gap: it walks every plugin's init() call graph and errors on
+ * any init-reachable getService of a workspace-provided service that no
+ * declaration covers. Best-effort tolerance is declared IN the plugin via
+ * `optionalDependencies`, never exempted in the checker.
+ */
+/**
+ * The ordering-relevant surface of a kernel plugin. Structural on purpose:
+ * ObjectKernel sorts `PluginMetadata`, LiteKernel sorts `Plugin`, and both
+ * satisfy this shape.
+ */
+interface OrderablePlugin {
+    name: string;
+    /** Hard dependencies — hoisted ahead; missing ⇒ boot error. */
+    dependencies?: string[];
+    /** Soft dependencies — hoisted ahead when composed, skipped when absent. */
+    optionalDependencies?: string[];
+    /** Services resolved synchronously during init(). */
+    requiresServices?: string[];
+    /** Services init() unconditionally registers. */
+    providesServices?: string[];
+}
+/**
+ * Topologically order plugins: every plugin's `dependencies` (throw when
+ * missing) and `optionalDependencies` (skip when missing) init before it.
+ * Insertion order is preserved for plugins with no edges between them.
+ * Cycles through either edge kind throw — an optional dependency is a real
+ * edge whenever both sides are composed.
+ */
+declare function resolvePluginOrder<P extends OrderablePlugin>(plugins: Map<string, P>): P[];
+/**
+ * Pre-Phase-1 check: walk the resolved order and prove no plugin requires a
+ * service whose only declared provider initializes AFTER it. A violation is
+ * the exact #4085 class — misplaced composition — reported as a named,
+ * structural boot error BEFORE any init side effects, instead of a bare
+ * "Service not found" thrown from inside the victim's init.
+ *
+ * Deliberately does NOT fail when a required service has no declared provider
+ * and is not yet registered: an earlier plugin may register it without
+ * declaring `providesServices`. That case is settled authoritatively by
+ * {@link assertInitServiceRequirements} immediately before the requiring
+ * plugin's init runs.
+ */
+declare function validateInitServiceContract<P extends OrderablePlugin>(ordered: P[], isServiceRegistered: (name: string) => boolean): void;
+/**
+ * Diagnosis suffix for a getService miss that happens WHILE a plugin's
+ * init() is running: names the initializing plugin and — when a composed
+ * plugin declares the service — the provider and the directive to declare
+ * the ordering. Returns '' when no plugin is initializing, so non-boot
+ * error messages stay byte-identical. Shared by both kernels.
+ */
+declare function describeInitOrderFault(currentlyInitializing: string | undefined, plugins: Iterable<OrderablePlugin>, serviceName: string): string;
+/**
+ * Just-before-init check: every service in `requiresServices` must be
+ * registered at the moment the plugin's init() is about to run. At this
+ * point the verdict is authoritative — Phase 1 runs sequentially, so a
+ * service absent now is absent for this init, and the init would die on a
+ * bare "Service not found" anyway. This turns that crash into a named
+ * composition error.
+ */
+declare function assertInitServiceRequirements(plugin: OrderablePlugin, isServiceRegistered: (name: string) => boolean): void;
+
 /**
  * ObjectKernel - MiniKernel Architecture
  *
@@ -1997,18 +2198,16 @@ declare function evaluateAuthGate(sessionUser: any, path: string): AuthGate | nu
 
 /** HTTP status every seam returns for an anonymous-denied request. */
 declare const ANONYMOUS_DENY_STATUS: 401;
-/** Stable machine code (mirrors the REST `enforceAuth` seam). */
-declare const ANONYMOUS_DENY_CODE: "unauthenticated";
+/** Stable machine code (mirrors the REST `enforceAuth` seam). ADR-0112: SCREAMING, a `StandardErrorCode` member. */
+declare const ANONYMOUS_DENY_CODE: "UNAUTHENTICATED";
 /** Human-facing message. */
 declare const ANONYMOUS_DENY_MESSAGE = "Authentication is required to access this endpoint.";
 /** The single 401 body shape every seam returns: `{ error, message }`. */
 declare const ANONYMOUS_DENY_BODY: {
-    readonly error: "unauthenticated";
+    readonly error: "UNAUTHENTICATED";
     readonly message: "Authentication is required to access this endpoint.";
 };
 interface AnonymousDenyInput {
-    /** The `requireAuth` posture. Falsy ⇒ no-op (demo / single-tenant). */
-    requireAuth: boolean | undefined;
     /** Resolved caller id, if any. */
     userId?: string | null;
     /** Internal system context (never set on inbound HTTP; cannot be forged). */
@@ -2115,6 +2314,7 @@ declare function calendarPartsInTzOrUtc(d: Date, tz?: string): CalendarParts;
  * reference-tz calendar, so its bucket boundary is that tz's midnight instant.
  */
 declare function zonedDateStartToUtcMs(ymd: string, tz?: string): number;
+
 /**
  * Granularity of a canonical date-bucket key. Mirrors `@objectstack/spec`'s
  * `DateGranularity` enum but kept as a local literal union so this low-level
@@ -2265,6 +2465,203 @@ declare function withTransientRetry<T>(fn: (attempt: number) => Promise<T>, opts
  */
 declare function bulkWrite<TRow, TRecord = any>(rows: TRow[], opts: BulkWriteOptions<TRow, TRecord>): Promise<BulkWriteRowResult<TRecord>[]>;
 
+/**
+ * Can this runtime actually roll back? — the ADR-0119 D4 gate, shared.
+ *
+ * Exported from `@objectstack/core` and consumed by
+ * `@objectstack/metadata-protocol`'s `batchData` (which depends on core, so
+ * the direction is legal) so the two cannot drift. They were the same two-line
+ * condition written twice, which is precisely the shape that drifts by one
+ * clause and leaves one caller believing it has atomicity it does not have.
+ *
+ * TWO levels, both necessary. `engine.transaction()` exists but runs the
+ * callback with NO transaction and NO rollback when the default driver lacks
+ * `beginTransaction` — a declared caveat of the contract member (ADR-0119 D1),
+ * and one that turns "atomic" back into a lie precisely where it matters. So
+ * where the driver registry is inspectable the driver is checked too; where it
+ * is not (test doubles), the engine-level probe is all there is.
+ *
+ * A type predicate, not a bare boolean: every caller's next move is to CALL
+ * `transaction`, and on the host surfaces that declare it optionally
+ * (`MetadataHostEngine`) a boolean would leave each one re-narrowing by hand —
+ * which is the same restatement this helper exists to remove.
+ */
+declare function engineCanRollBack<T>(engine: T): engine is T & EngineWithTransaction;
+/** What {@link engineCanRollBack} proves is present. Mirrors `IObjectQLEngine['transaction']`. */
+interface EngineWithTransaction {
+    transaction<R>(callback: (trxCtx: any) => Promise<R>, baseContext?: any): Promise<R>;
+}
+/** What a forward/compensate callback is told about the chunk it is running. */
+interface MigrationChunkContext {
+    readonly runId: string;
+    /** Run-global chunk index — the LIFO ordering key, stable across a resume. */
+    readonly chunkIndex: number;
+    /**
+     * 1 on the first try. `> 1` means a previous attempt's outcome is UNKNOWN:
+     * recheck by natural key before re-writing (see this file's header).
+     */
+    readonly attempt: number;
+    /**
+     * The transaction-bound execution context. Thread it to every engine call
+     * this callback makes — `engine.insert(obj, row, { context })` — so the
+     * write joins the chunk's transaction instead of committing beside it.
+     */
+    readonly context: unknown;
+}
+/** One step of a plan. Steps run in declaration order; each is chunked. */
+interface MigrationPlanStep<TRow = unknown> {
+    readonly name: string;
+    /**
+     * Read-only preflight. Throw to refuse the run. Runs for EVERY step before
+     * any step writes — a plan that would fail at step 3 must not have written
+     * step 1 (ADR-0117 D8's fail-closed enable gate, generalized).
+     */
+    preflight?(engine: IObjectQLEngine): Promise<void>;
+    /** The rows this step processes. Called once, before chunking. */
+    load(engine: IObjectQLEngine): Promise<TRow[]>;
+    /** Forward work for one chunk. Runs INSIDE the chunk's transaction. */
+    forward(rows: TRow[], ctx: MigrationChunkContext, engine: IObjectQLEngine): Promise<void>;
+    /**
+     * Undo one previously-committed chunk. Runs in its OWN transaction.
+     * A step without one makes the plan non-compensable — which the runner
+     * refuses up front rather than discovering at the worst possible moment
+     * (see {@link runMigrationJournal}'s preflight).
+     */
+    compensate?(rows: TRow[], ctx: MigrationChunkContext, engine: IObjectQLEngine): Promise<void>;
+}
+interface MigrationPlan {
+    /** Stable plan id. Part of the plan hash; identifies the plan across runs. */
+    readonly id: string;
+    /** Optional join to `sys_migration.id` when this plan implements a named migration. */
+    readonly migrationId?: string;
+    readonly steps: ReadonlyArray<MigrationPlanStep<any>>;
+    readonly chunkSize?: number;
+    /**
+     * What a REDISCOVERED (crashed) run should do. Note this governs restart
+     * only — an in-run failure always compensates, because the runner is still
+     * alive to do it and a half-applied plan is nobody's intent.
+     */
+    readonly onCrash?: MigrationOnCrashPolicy;
+}
+/** One chunk in the run-global chunk plan. */
+interface MigrationChunk {
+    /** Run-global index, 0-based, stable for a given plan hash. */
+    readonly index: number;
+    readonly stepIndex: number;
+    readonly stepName: string;
+    readonly offset: number;
+    readonly length: number;
+}
+interface MigrationRunResult {
+    readonly runId: string;
+    /**
+     * `completed` — every chunk committed.
+     * `compensated` — a chunk failed and every committed chunk was undone.
+     * `failed` — a chunk failed AND compensation could not finish. The database
+     *   is in a partial state that needs a human; the journal says exactly where.
+     */
+    readonly status: 'completed' | 'compensated' | 'failed';
+    readonly chunksTotal: number;
+    readonly chunksCommitted: number;
+    readonly chunksCompensated: number;
+    readonly planHash: string;
+    /** The failure that ended a non-`completed` run. */
+    readonly error?: unknown;
+}
+/**
+ * Where a resume finds the plan it has to re-run (#4617).
+ *
+ * A journal cannot hold a plan. `forward` and `compensate` are FUNCTIONS, and
+ * the rows a chunk covers are produced by `load()` against the live database —
+ * none of it survives a process boundary, which is why the journal records the
+ * plan HASH rather than the plan. So recovery needs the plan handed back to it
+ * by whoever owns the code, and that is what this registry is: the seam between
+ * "the journal knows a run stopped at chunk 7" and "something in this process
+ * knows what chunk 7 was supposed to do".
+ *
+ * Registered as the `migration-plans` kernel service. An interrupted run whose
+ * plan no loaded plugin registers is REPORTED, never silently skipped — the
+ * operator is told which plan id is missing, because "nothing to resume" and
+ * "the code that owns this run is not loaded" are different facts and only one
+ * of them is safe to ignore.
+ */
+interface MigrationPlanProvider {
+    register(plan: MigrationPlan): void;
+    get(planId: string): MigrationPlan | undefined;
+    list(): MigrationPlan[];
+}
+/** The default {@link MigrationPlanProvider}. Last registration for an id wins. */
+declare class MigrationPlanRegistry implements MigrationPlanProvider {
+    private readonly plans;
+    register(plan: MigrationPlan): void;
+    get(planId: string): MigrationPlan | undefined;
+    list(): MigrationPlan[];
+}
+/** A run found by {@link findInterruptedRuns} — started, never concluded. */
+interface InterruptedRun {
+    readonly runId: string;
+    readonly planId: string;
+    readonly planHash: string;
+    readonly migrationId?: string;
+    readonly startedAt?: string;
+    /** Chunks whose `chunk_done` is present — known committed. */
+    readonly committedChunks: number[];
+    /** Chunks with `chunk_started` and no `chunk_done` — outcome UNKNOWN. */
+    readonly unknownChunks: number[];
+    readonly compensatedChunks: number[];
+}
+/** Raised when the runner refuses to start or to resume. Never a partial run. */
+declare class MigrationJournalRefusal extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Flatten steps × rows into the run-global chunk list. */
+declare function planChunks(plan: MigrationPlan, rowCounts: readonly number[], chunkSize?: number): MigrationChunk[];
+/**
+ * Hash the plan SHAPE — id, step names, and the chunk boundaries.
+ *
+ * Resuming a changed plan against an old journal would apply chunk boundaries
+ * the journal never described: "chunk 7 done" would name a different range of
+ * different rows, and the resume would skip work it never did. So the hash
+ * covers exactly what a chunk index means, and a mismatch REFUSES.
+ */
+declare function hashMigrationPlan(plan: MigrationPlan, chunks: readonly MigrationChunk[]): string;
+/**
+ * Every event for a run, ordered by `seq`.
+ *
+ * Sorted in memory, deliberately. `seq` is the ordering authority (wall-clock
+ * stamps tie at coarse resolution and skew), and a run's journal is bounded by
+ * its chunk count, so this costs nothing and removes recovery's dependence on
+ * driver-side sort behaviour — which is not something a recovery path should
+ * be discovering the edges of.
+ */
+declare function readRunJournal(engine: IObjectQLEngine, runId: string): Promise<MigrationJournalEvent[]>;
+/**
+ * Runs that started and never concluded — the boot scanner's input.
+ *
+ * "Concluded" means `run_done` (finished forward) or `run_failed` with every
+ * committed chunk compensated (finished backward). Anything else is a run that
+ * stopped mid-flight and still owes the operator an answer.
+ */
+declare function findInterruptedRuns(engine: IObjectQLEngine): Promise<InterruptedRun[]>;
+interface RunMigrationJournalOptions {
+    /** Supply to resume an existing run; omit to start a new one. */
+    readonly runId?: string;
+    readonly chunkSize?: number;
+    /** Injectable for deterministic tests. */
+    readonly now?: () => string;
+}
+/**
+ * Run `plan` under the journal, or resume a run left behind by a crash.
+ *
+ * Refuses (never partially runs) when: the runtime cannot roll back; any
+ * step's preflight fails; the plan declares `onCrash: 'compensate'` but some
+ * step cannot compensate; or a resume's plan hash disagrees with the journal.
+ */
+declare function runMigrationJournal(engine: IObjectQLEngine, plan: MigrationPlan, options?: RunMigrationJournalOptions): Promise<MigrationRunResult>;
+/** Resume a run the journal says was interrupted. Thin alias for intent at call sites. */
+declare function resumeMigrationJournal(engine: IObjectQLEngine, plan: MigrationPlan, runId: string, options?: Omit<RunMigrationJournalOptions, 'runId'>): Promise<MigrationRunResult>;
+
 /**
  * The slice of an execution context the resolver reads. Structural on purpose —
  * see {@link filterTokenContextFrom}.
@@ -2357,9 +2754,22 @@ declare function filterTokenContextFrom(execCtx: ExecutionContextLike | undefine
  * Implements the ICacheService contract with basic get/set/delete/has/clear
  * and TTL expiry.  Used by ObjectKernel as an automatic fallback when no
  * real cache plugin (e.g. Redis) is registered.
+ *
+ * [#4058] Self-describes as `degraded`, not `stub` (ADR-0076 D12): this is a
+ * real cache — it stores, expires, and reports true stats — just process-local
+ * and unshared. The non-standard `_fallback: true` it used to carry was read by
+ * nothing (`readServiceSelfInfo` reads only `__serviceInfo` — `_dev`, the other
+ * marker it knew back then, was itself retired in #4319), so discovery reported
+ * it as fully `available`. `handlerReady: false` because
+ * no HTTP surface is mounted for `cache` at all — the same reason realtime
+ * reports false.
  */
 declare function createMemoryCache(): {
-    _fallback: boolean;
+    __serviceInfo: {
+        status: "degraded";
+        handlerReady: boolean;
+        message: string;
+    };
     _serviceName: string;
     get<T = unknown>(key: string): Promise<T | undefined>;
     set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
@@ -2379,9 +2789,18 @@ declare function createMemoryCache(): {
  * Implements the IQueueService contract with synchronous in-process delivery.
  * Used by ObjectKernel as an automatic fallback when no real queue plugin
  * (e.g. BullMQ / RabbitMQ) is registered.
+ *
+ * [#4058] `degraded`, not `stub` (ADR-0076 D12): messages really reach real
+ * subscribers — synchronously, in-process, with no durability or retry.
+ * `getQueueSize()` answering 0 follows from that rather than faking it: nothing
+ * is ever buffered. `handlerReady: false` — no HTTP surface exists for `queue`.
  */
 declare function createMemoryQueue(): {
-    _fallback: boolean;
+    __serviceInfo: {
+        status: "degraded";
+        handlerReady: boolean;
+        message: string;
+    };
     _serviceName: string;
     publish<T = unknown>(queue: string, data: T): Promise<string>;
     subscribe(queue: string, handler: (msg: any) => Promise<void>): Promise<void>;
@@ -2396,9 +2815,19 @@ declare function createMemoryQueue(): {
  * Implements the IJobService contract with basic schedule/cancel/trigger
  * operations.  Used by ObjectKernel as an automatic fallback when no real
  * job plugin (e.g. Agenda / BullMQ) is registered.
+ *
+ * [#4058] `degraded` (ADR-0076 D12), with the missing half named in the
+ * message rather than left for a deployer to discover: `trigger()` really runs
+ * the registered handler, but nothing here owns a timer, so a `schedule()`d job
+ * NEVER fires on its own. That is reduced capability, not fabricated output —
+ * no call returns a made-up answer. `handlerReady: false`: no HTTP surface.
  */
 declare function createMemoryJob(): {
-    _fallback: boolean;
+    __serviceInfo: {
+        status: "degraded";
+        handlerReady: boolean;
+        message: string;
+    };
     _serviceName: string;
     schedule(name: string, schedule: any, handler: any): Promise<void>;
     cancel(name: string): Promise<void>;
@@ -2439,7 +2868,10 @@ declare function resolveLocale(requestedLocale: string, availableLocales: string
  * Does not load files from disk — operates purely in-memory.
  */
 declare function createMemoryI18n(): {
-    _fallback: boolean;
+    __serviceInfo: {
+        status: "degraded";
+        message: string;
+    };
     _serviceName: string;
     t(key: string, locale: string, params?: Record<string, unknown>): string;
     getTranslations(locale: string): Record<string, unknown>;
@@ -2464,7 +2896,10 @@ declare function createMemoryI18n(): {
  * (e.g. MetadataPlugin with file-system persistence) is registered.
  */
 declare function createMemoryMetadata(): {
-    _fallback: boolean;
+    __serviceInfo: {
+        status: "degraded";
+        message: string;
+    };
     _serviceName: string;
     register(type: string, name: string, data: any): Promise<void>;
     registerInMemory(type: string, name: string, data: any): void;
@@ -2787,4 +3222,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-export { ANONYMOUS_DENY_BODY, ANONYMOUS_DENY_CODE, ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS, API_KEY_PREFIX, type AnonymousDenyInput, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, type AuthGate, type BucketGranularity, type BulkWriteOptions, type BulkWriteRowResult, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type ExecutionContextLike, type FilterTokenResolutionContext, type GeneratedApiKey, type GrantValidityWindow, HotReloadManager, type KernelState, type KeyInput, type LadderPrincipal, type LadderRow, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, POSTURE_INJECTION_RULE, POSTURE_LADDER, POSTURE_RANK, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PostureEvidence, type PublisherVerifyResult, index as QA, type ResolveAuthzInput, type ResolveLocalizationInput, type ResolveUserAuthzGrantsOptions, type ResolvedAuthzContext, type ResourceUsage, type RetryOptions, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, UnknownFilterTokenError, UnresolvedFilterTokenError, type UserAuthzGrants, type VersionCompatibility, bucketKeyToCalendarRange, buildPermissionsFromGrants, bulkWrite, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, deepMerge, defaultIsTransientError, derivePosture, evaluateAuthGate, extractApiKey, filterTokenContextFrom, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isAuthGateAllowlisted, isExpired, isGrantActive, isGrantExpired, isNode, parseScopes, parseSignature, postureVisibleRows, readAuthoredTranslationLayer, resolveApiKeyPrincipal, resolveAuthzContext, resolveFilterToken, resolveFilterTokens, resolveLocale, resolveLocalizationContext, resolveUserAuthzGrants, safeExit, shouldDenyAnonymous, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature, wireAuthoredTranslationSync, withTransientRetry, zonedDateStartToUtcMs };
+export { ANONYMOUS_DENY_BODY, ANONYMOUS_DENY_CODE, ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS, API_KEY_PREFIX, type AnonymousDenyInput, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, type AuthGate, type BucketGranularity, type BulkWriteOptions, type BulkWriteRowResult, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type EngineWithTransaction, type ExecutionContextLike, type FilterTokenResolutionContext, type GeneratedApiKey, type GrantValidityWindow, HotReloadManager, type InterruptedRun, type KernelState, type KeyInput, type LadderPrincipal, type LadderRow, LiteKernel, type MigrationChunk, type MigrationChunkContext, MigrationJournalRefusal, type MigrationPlan, type MigrationPlanProvider, MigrationPlanRegistry, type MigrationPlanStep, type MigrationRunResult, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type OrderablePlugin, POSTURE_INJECTION_RULE, POSTURE_LADDER, POSTURE_RANK, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PostureEvidence, type PublisherVerifyResult, index as QA, type ResolveAuthzInput, type ResolveLocalizationInput, type ResolveUserAuthzGrantsOptions, type ResolvedAuthzContext, type ResourceUsage, type RetryOptions, type RunMigrationJournalOptions, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, UnknownFilterTokenError, UnresolvedFilterTokenError, type UserAuthzGrants, type VersionCompatibility, assertInitServiceRequirements, bucketKeyToCalendarRange, buildPermissionsFromGrants, bulkWrite, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, deepMerge, defaultIsTransientError, derivePosture, describeInitOrderFault, engineCanRollBack, evaluateAuthGate, extractApiKey, filterTokenContextFrom, findInterruptedRuns, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, hashMigrationPlan, isAuthGateAllowlisted, isExpired, isGrantActive, isGrantExpired, isNode, parseScopes, parseSignature, planChunks, postureVisibleRows, readAuthoredTranslationLayer, readRunJournal, resolveApiKeyPrincipal, resolveAuthzContext, resolveFilterToken, resolveFilterTokens, resolveLocale, resolveLocalizationContext, resolvePluginOrder, resolveUserAuthzGrants, resumeMigrationJournal, runMigrationJournal, safeExit, shouldDenyAnonymous, signPayload, validateInitServiceContract, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature, wireAuthoredTranslationSync, withTransientRetry, zonedDateStartToUtcMs };