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

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { Logger, LifecycleEventName, IServiceRegistry } 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';
@@ -297,6 +297,30 @@ 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
@@ -605,6 +629,16 @@ declare abstract class ObjectKernelBase {
  *    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:
@@ -2431,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}.
@@ -2991,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, 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, 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, evaluateAuthGate, extractApiKey, filterTokenContextFrom, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isAuthGateAllowlisted, isExpired, isGrantActive, isGrantExpired, isNode, parseScopes, parseSignature, postureVisibleRows, readAuthoredTranslationLayer, resolveApiKeyPrincipal, resolveAuthzContext, resolveFilterToken, resolveFilterTokens, resolveLocale, resolveLocalizationContext, resolvePluginOrder, resolveUserAuthzGrants, safeExit, shouldDenyAnonymous, signPayload, validateInitServiceContract, 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 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { Logger, LifecycleEventName, IServiceRegistry } 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.js';
 export { createLogger } from './logger.js';
 import { ConflictResolutionStrategy, ApiRegistryEntryInput, ApiRegistryEntry, ApiDiscoveryQuery, ApiDiscoveryResponse, ApiEndpointRegistration, ApiRegistry as ApiRegistry$1 } from '@objectstack/spec/api';
@@ -297,6 +297,30 @@ 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
@@ -605,6 +629,16 @@ declare abstract class ObjectKernelBase {
  *    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:
@@ -2431,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}.
@@ -2991,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, 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, 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, evaluateAuthGate, extractApiKey, filterTokenContextFrom, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isAuthGateAllowlisted, isExpired, isGrantActive, isGrantExpired, isNode, parseScopes, parseSignature, postureVisibleRows, readAuthoredTranslationLayer, resolveApiKeyPrincipal, resolveAuthzContext, resolveFilterToken, resolveFilterTokens, resolveLocale, resolveLocalizationContext, resolvePluginOrder, resolveUserAuthzGrants, safeExit, shouldDenyAnonymous, signPayload, validateInitServiceContract, 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 };