@crowi/api 2.0.0-alpha.0

package/dist/migration/rebuilds/index.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backlinkRebuild = exports.searchRebuild = void 0;
+exports.storageCopyRebuild = storageCopyRebuild;
+exports.rendererRebuild = rendererRebuild;
+const rebuild_backlink_1 = require("../../util/rebuild-backlink");
+const rebuild_renderer_1 = require("../../util/rebuild-renderer");
+const search_rebuild_1 = require("../../util/search-rebuild");
+const storage_copy_1 = require("../../util/storage-copy");
+const rebuild_runner_1 = require("../rebuild-runner");
+/**
+ * RFC-0008 §8.5 — the registered rebuild tasks.
+ *
+ * Each task wires an existing api-side `run*` helper onto the shared
+ * `RebuildRunner` so the `--dry-run` / progress / SIGINT / structured-logging
+ * conventions are uniform. Tasks carry NO pending/applied state (§8.5): they
+ * never read or append `migrationApplications`.
+ *
+ * `search` and `storage-copy` port the previously top-level `search rebuild` /
+ * `storage copy` commands (their core logic stays in `util/`, unchanged);
+ * `renderer` and `backlink` are skeletons whose `run*` helpers throw a clear
+ * "not implemented" error (no legacy implementation to port).
+ */
+exports.searchRebuild = (0, rebuild_runner_1.defineRebuild)({
+    id: 'search',
+    description: "Rebuild the search index from scratch using the active driver's rebuild().",
+    async run(ctx) {
+        const summary = await (0, search_rebuild_1.runSearchRebuild)(ctx.crowi);
+        return { driverName: summary.driverName, pluginName: summary.pluginName };
+    },
+});
+function storageCopyRebuild(opts) {
+    return (0, rebuild_runner_1.defineRebuild)({
+        id: 'storage-copy',
+        description: `Copy every stored object from '${opts.from}' to '${opts.to}'.`,
+        async run(ctx) {
+            const summary = await (0, storage_copy_1.runStorageCopy)(ctx.crowi, {
+                from: opts.from,
+                to: opts.to,
+                dryRun: ctx.dryRun,
+                onProgress: (event) => {
+                    // Bridge the util's per-key callback onto the shared progress sink.
+                    ctx.progress.increment();
+                    ctx.progress.setLabel(`${event.stage} ${event.key}`);
+                },
+            });
+            return { ...summary };
+        },
+    });
+}
+function rendererRebuild(opts) {
+    return (0, rebuild_runner_1.defineRebuild)({
+        id: 'renderer',
+        description: 'Regenerate cached rendered HTML for pages. (not implemented)',
+        async run(ctx) {
+            const summary = await (0, rebuild_renderer_1.runRendererRebuild)(ctx.crowi, { onlyStale: opts.onlyStale });
+            return { ...summary };
+        },
+    });
+}
+exports.backlinkRebuild = (0, rebuild_runner_1.defineRebuild)({
+    id: 'backlink',
+    description: 'Rebuild the backlink index across all pages. (not implemented)',
+    async run(ctx) {
+        const summary = await (0, rebuild_backlink_1.runBacklinkRebuild)(ctx.crowi);
+        return { ...summary };
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/migration/rebuilds/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/migration/rebuilds/index.ts"],"names":[],"mappings":";;;AAoCA,gDAkBC;AAMD,0CASC;AArED,gEAA+D;AAC/D,gEAA+D;AAC/D,4DAA2D;AAC3D,wDAAiF;AAEjF,sDAAoE;AAEpE;;;;;;;;;;;;GAYG;AAEU,QAAA,aAAa,GAAgB,IAAA,8BAAa,EAAC;IACtD,EAAE,EAAE,QAAQ;IACZ,WAAW,EAAE,4EAA4E;IACzF,KAAK,CAAC,GAAG,CAAC,GAAG;QACX,MAAM,OAAO,GAAG,MAAM,IAAA,iCAAgB,EAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClD,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;IAC5E,CAAC;CACF,CAAC,CAAC;AAQH,SAAgB,kBAAkB,CAAC,IAA4B;IAC7D,OAAO,IAAA,8BAAa,EAAC;QACnB,EAAE,EAAE,cAAc;QAClB,WAAW,EAAE,kCAAkC,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,IAAI;QAC5E,KAAK,CAAC,GAAG,CAAC,GAAG;YACX,MAAM,OAAO,GAAG,MAAM,IAAA,6BAAc,EAAC,GAAG,CAAC,KAAK,EAAE;gBAC9C,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,UAAU,EAAE,CAAC,KAA0B,EAAE,EAAE;oBACzC,oEAAoE;oBACpE,GAAG,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;oBACzB,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;gBACvD,CAAC;aACF,CAAC,CAAC;YACH,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;QACxB,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAMD,SAAgB,eAAe,CAAC,IAAyB;IACvD,OAAO,IAAA,8BAAa,EAAC;QACnB,EAAE,EAAE,UAAU;QACd,WAAW,EAAE,8DAA8D;QAC3E,KAAK,CAAC,GAAG,CAAC,GAAG;YACX,MAAM,OAAO,GAAG,MAAM,IAAA,qCAAkB,EAAC,GAAG,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;YACnF,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;QACxB,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAEY,QAAA,eAAe,GAAgB,IAAA,8BAAa,EAAC;IACxD,EAAE,EAAE,UAAU;IACd,WAAW,EAAE,gEAAgE;IAC7E,KAAK,CAAC,GAAG,CAAC,GAAG;QACX,MAAM,OAAO,GAAG,MAAM,IAAA,qCAAkB,EAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpD,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;IACxB,CAAC;CACF,CAAC,CAAC"}

package/dist/migration/registry.d.ts

@@ -0,0 +1,15 @@
+import type { MigrationDefinition, MigrationLayer } from './types';
+export declare class MigrationRegistry {
+    private readonly migrations;
+    constructor(defs: MigrationDefinition[]);
+    /** All migrations in version-range + `order` sequence. */
+    all(): readonly MigrationDefinition[];
+    /** Migrations of a given layer, in order. */
+    byLayer(layer: MigrationLayer): readonly MigrationDefinition[];
+    /** Look up a migration by id, or undefined. */
+    get(id: string): MigrationDefinition | undefined;
+    /** The latest reachable target version across all registered migrations. */
+    latestTarget(): string | null;
+}
+/** The default registry built from the `migrations/` barrel. */
+export declare function createRegistry(defs?: MigrationDefinition[]): MigrationRegistry;

package/dist/migration/registry.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MigrationRegistry = void 0;
+exports.createRegistry = createRegistry;
+const migrations_1 = require("./migrations");
+/**
+ * RFC-0008 §5.5 — the migration registry.
+ *
+ * Loads every `MigrationDefinition` from the `migrations/` barrel and
+ * exposes them in a stable, deterministic order: by version range, then by
+ * `order` within the same range (defaulting to declaration order). There is
+ * no cross-migration dependency graph (§5.3) — version range + `order` is
+ * the only ordering input.
+ *
+ * The registry is intentionally a pure, in-memory structure with no DB
+ * access; pending determination and application live in `runner.ts`.
+ */
+/**
+ * Parse a version string into a comparable numeric tuple. We only need a
+ * total order over the handful of ranges this codebase uses ('1.x', '2.0',
+ * '2.1', ...). 'x' / missing minor sorts as 0 so '1.x' precedes '2.0'.
+ *
+ * This is deliberately lenient (not full semver): migration versions are
+ * coarse upgrade milestones, not package versions.
+ */
+function versionKey(version) {
+    const [majorRaw, minorRaw] = version.split('.');
+    const major = Number.parseInt(majorRaw ?? '0', 10);
+    const minor = minorRaw === undefined || minorRaw === 'x' ? 0 : Number.parseInt(minorRaw, 10);
+    return [Number.isNaN(major) ? 0 : major, Number.isNaN(minor) ? 0 : minor];
+}
+function compareVersion(a, b) {
+    const [aMaj, aMin] = versionKey(a);
+    const [bMaj, bMin] = versionKey(b);
+    if (aMaj !== bMaj)
+        return aMaj - bMaj;
+    return aMin - bMin;
+}
+/**
+ * Total order over migrations: by `fromVersion`, then `toVersion`, then
+ * `order` (defaulting to the migration's index in the source array so the
+ * sort is stable and mirrors declaration order).
+ */
+function compareMigrations(a, b, indexOf) {
+    const fromCmp = compareVersion(a.fromVersion, b.fromVersion);
+    if (fromCmp !== 0)
+        return fromCmp;
+    const toCmp = compareVersion(a.toVersion, b.toVersion);
+    if (toCmp !== 0)
+        return toCmp;
+    const aOrder = a.order ?? indexOf.get(a.id) ?? 0;
+    const bOrder = b.order ?? indexOf.get(b.id) ?? 0;
+    if (aOrder !== bOrder)
+        return aOrder - bOrder;
+    return (indexOf.get(a.id) ?? 0) - (indexOf.get(b.id) ?? 0);
+}
+class MigrationRegistry {
+    migrations;
+    constructor(defs) {
+        // Guard against duplicate ids early — ids are stable keys in
+        // `migrationApplications`, so a collision would corrupt the audit log.
+        const seen = new Set();
+        for (const def of defs) {
+            if (seen.has(def.id)) {
+                throw new Error(`Duplicate migration id in registry: '${def.id}'`);
+            }
+            seen.add(def.id);
+        }
+        const indexOf = new Map(defs.map((def, i) => [def.id, i]));
+        this.migrations = [...defs].sort((a, b) => compareMigrations(a, b, indexOf));
+    }
+    /** All migrations in version-range + `order` sequence. */
+    all() {
+        return this.migrations;
+    }
+    /** Migrations of a given layer, in order. */
+    byLayer(layer) {
+        return this.migrations.filter((m) => m.layer === layer);
+    }
+    /** Look up a migration by id, or undefined. */
+    get(id) {
+        return this.migrations.find((m) => m.id === id);
+    }
+    /** The latest reachable target version across all registered migrations. */
+    latestTarget() {
+        if (this.migrations.length === 0)
+            return null;
+        return this.migrations.reduce((latest, m) => (compareVersion(m.toVersion, latest) > 0 ? m.toVersion : latest), this.migrations[0].toVersion);
+    }
+}
+exports.MigrationRegistry = MigrationRegistry;
+/** The default registry built from the `migrations/` barrel. */
+function createRegistry(defs = migrations_1.allMigrations) {
+    return new MigrationRegistry(defs);
+}
+//# sourceMappingURL=registry.js.map

package/dist/migration/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/migration/registry.ts"],"names":[],"mappings":"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"}

package/dist/migration/run-boot-migrations.d.ts

@@ -0,0 +1,31 @@
+import type Crowi from '../crowi';
+import { type MigrationRegistry } from './registry';
+import { type PreflightUnappliedPolicy } from './runner';
+import type { MigrationLogger } from './types';
+/** Error thrown when boot is refused under the `block` policy. */
+export declare class PreflightBlockedError extends Error {
+    readonly pendingIds: string[];
+    constructor(pendingIds: string[]);
+}
+/**
+ * Resolve the preflight-unapplied policy. Env var override (§12.7) wins over
+ * the `migration.preflightUnappliedPolicy` config namespace, which in turn
+ * defaults to `block`.
+ */
+export declare function resolvePreflightPolicy(crowi: Crowi): PreflightUnappliedPolicy;
+export interface RunBootMigrationsOptions {
+    /** Override the registry (tests inject a registry of fixture migrations). */
+    registry?: MigrationRegistry;
+    /** Override the policy resolution (tests). */
+    policy?: PreflightUnappliedPolicy;
+    /** Live force-reload broadcast for boot-layer migrations (api process). */
+    broadcastForceReload?: (pageIds: string[]) => Promise<void>;
+    /** Logger override (tests / quiet boot). */
+    logger?: MigrationLogger;
+}
+export interface RunBootMigrationsResult {
+    appliedBootIds: string[];
+    pendingPreflightIds: string[];
+    policy: PreflightUnappliedPolicy;
+}
+export declare function runBootMigrations(crowi: Crowi, options?: RunBootMigrationsOptions): Promise<RunBootMigrationsResult>;

package/dist/migration/run-boot-migrations.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreflightBlockedError = void 0;
+exports.resolvePreflightPolicy = resolvePreflightPolicy;
+exports.runBootMigrations = runBootMigrations;
+const registry_1 = require("./registry");
+const runner_1 = require("./runner");
+/**
+ * RFC-0008 §4.2.1 — the boot-sequence migration step.
+ *
+ * Called from `crowi/index.ts` during init. Two responsibilities:
+ *
+ *   1. Apply every `layer:'boot'` migration that `isPending` flags, in
+ *      version-range + `order` sequence, appending each result to the
+ *      `migrationApplications` audit log.
+ *   2. Probe every `layer:'preflight'` migration with `isPending` (cheap)
+ *      and, when any is unapplied, either refuse boot (`block`, default) or
+ *      log loudly and continue (`warn`) — per `preflightUnappliedPolicy`.
+ *
+ * `block` is the safe default (§4.2.7): if a preflight migration hasn't run
+ * before v2 boot, *every replica fail-fasts* with a clear error before
+ * autoIndex would otherwise hit E11000 (§9) on not-yet-deduped data. The
+ * operator then runs `crowi-admin migrate apply` once and brings the cluster
+ * up.
+ *
+ * Phase 1 ships with an empty registry, so this is a fast no-op; the wiring
+ * is what matters. Phase 2 adds `page-status-default` as the first boot
+ * migration.
+ */
+const POLICY_ENV_VAR = 'MIGRATION_PREFLIGHT_UNAPPLIED_POLICY';
+/** Error thrown when boot is refused under the `block` policy. */
+class PreflightBlockedError extends Error {
+    pendingIds;
+    constructor(pendingIds) {
+        super(`Boot refused: ${pendingIds.length} preflight migration(s) are unapplied [${pendingIds.join(', ')}]. ` +
+            'Run `crowi-admin migrate apply` against this database before starting the application ' +
+            `(set ${POLICY_ENV_VAR}=warn to override at your own risk).`);
+        this.name = 'PreflightBlockedError';
+        this.pendingIds = pendingIds;
+    }
+}
+exports.PreflightBlockedError = PreflightBlockedError;
+/**
+ * Resolve the preflight-unapplied policy. Env var override (§12.7) wins over
+ * the `migration.preflightUnappliedPolicy` config namespace, which in turn
+ * defaults to `block`.
+ */
+function resolvePreflightPolicy(crowi) {
+    const fromEnv = crowi.env[POLICY_ENV_VAR];
+    if (fromEnv === 'warn' || fromEnv === 'block')
+        return fromEnv;
+    const cfg = crowi.getConfig();
+    const fromConfig = cfg?.migration?.preflightUnappliedPolicy;
+    if (fromConfig === 'warn' || fromConfig === 'block')
+        return fromConfig;
+    return 'block';
+}
+async function runBootMigrations(crowi, options = {}) {
+    const registry = options.registry ?? (0, registry_1.createRegistry)();
+    const policy = options.policy ?? resolvePreflightPolicy(crowi);
+    const runner = new runner_1.MigrationRunner(crowi, {
+        appliedBy: 'boot-auto',
+        progress: runner_1.noopProgress,
+        logger: options.logger,
+        // Boot layer (api process) can broadcast a live force-reload; preflight
+        // probing below never mutates, so the handle is only meaningful here.
+        broadcastForceReload: options.broadcastForceReload,
+    });
+    // ── 1. Apply pending boot migrations in order ──
+    const appliedBootIds = [];
+    for (const def of registry.byLayer('boot')) {
+        const outcome = await runner.apply(def);
+        if (outcome.result === 'applied' || outcome.result === 're-applied') {
+            appliedBootIds.push(def.id);
+        }
+    }
+    // ── 2. Probe preflight migrations (cheap isPending) ──
+    const pendingPreflightIds = [];
+    for (const def of registry.byLayer('preflight')) {
+        if (await runner.isPending(def)) {
+            pendingPreflightIds.push(def.id);
+        }
+    }
+    if (pendingPreflightIds.length > 0) {
+        if (policy === 'block') {
+            // Whole-cluster fail-fast (§4.2.7).
+            throw new PreflightBlockedError(pendingPreflightIds);
+        }
+        // warn: operator explicitly accepts the risk.
+        console.warn(`[crowi:migration] WARNING: ${pendingPreflightIds.length} preflight migration(s) unapplied [${pendingPreflightIds.join(', ')}] ` +
+            `but ${POLICY_ENV_VAR}=warn — continuing boot. Data may not be in the target shape; autoIndex may fail with E11000.`);
+    }
+    return { appliedBootIds, pendingPreflightIds, policy };
+}
+//# sourceMappingURL=run-boot-migrations.js.map

package/dist/migration/run-boot-migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-boot-migrations.js","sourceRoot":"","sources":["../../src/migration/run-boot-migrations.ts"],"names":[],"mappings":"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"}

package/dist/migration/runner.d.ts

@@ -0,0 +1,120 @@
+import type Crowi from '../crowi';
+import type { MigrationResult } from '../models/migration-application';
+import type { DetectReport, MigrationContext, MigrationDefinition, MigrationLogger, ProgressReporter } from './types';
+/**
+ * RFC-0008 §4.3 — the shared migration runner.
+ *
+ * Both the `migrate` and `rebuild` namespaces route through this one runner
+ * so dry-run, progress, bounded concurrency, structured logging, safe SIGINT
+ * interruption, and Yjs invalidation are implemented once. It also owns the
+ * pending-vs-recorded reconciliation table (§6.2) and the append to the
+ * `migrationApplications` audit log.
+ */
+/** How the framework decides to handle an unapplied preflight migration at boot (§4.2.7). */
+export type PreflightUnappliedPolicy = 'block' | 'warn';
+export interface RunnerOptions {
+    /** When true, stages no-op and only `detect` runs (§8.2). */
+    dryRun?: boolean;
+    /** Bound on concurrent in-flight units a stage may schedule (default 8). */
+    concurrency?: number;
+    /** Identifies who triggered the run for the audit log ('boot-auto' | admin-cli@host). */
+    appliedBy?: string;
+    /** Optional progress sink; defaults to a no-op reporter. */
+    progress?: ProgressReporter;
+    /** Optional logger; defaults to a `debug`/console-backed logger. */
+    logger?: MigrationLogger;
+    /**
+     * Live force-reload broadcast, available ONLY in the api (boot) process.
+     * Left undefined by the admin CLI (§4.3.1).
+     */
+    broadcastForceReload?: (pageIds: string[]) => Promise<void>;
+}
+/** Outcome of running (or probing) a single migration. */
+export interface MigrationRunOutcome {
+    id: string;
+    result: MigrationResult;
+    durationMs: number;
+    stats: Record<string, unknown>;
+    /** True when the run was aborted by SIGINT before completing all stages. */
+    interrupted?: boolean;
+}
+/** A no-op progress reporter — used by boot / tests that don't render progress. */
+export declare const noopProgress: ProgressReporter;
+/**
+ * Resolve a runner's effective options, filling in defaults.
+ */
+declare function resolveOptions(opts: RunnerOptions): Required<Pick<RunnerOptions, 'dryRun' | 'concurrency' | 'appliedBy' | 'progress' | 'logger'>> & Pick<RunnerOptions, 'broadcastForceReload'>;
+/**
+ * RFC-0008 §4.3 — the shared runner *core*.
+ *
+ * Holds the booted Crowi, the resolved options, the per-run
+ * `MigrationContext` (dry-run / progress / logger / Yjs invalidation), the
+ * SIGINT-aware abort flag, and the bounded-concurrency limiter. This is the
+ * "shared infrastructure" both namespaces ride on: `migrate` adds the
+ * `migrationApplications` reconciliation/record path on top (`MigrationRunner`
+ * below), while `rebuild` rides on the core alone with **no** audit-log
+ * coupling (`RebuildRunner` in `rebuild-runner.ts`).
+ *
+ * Keeping the record path out of the core is deliberate (§8.5: rebuilds have
+ * "no pending/applied concept"): a rebuild can never accidentally append to
+ * `migrationApplications`, and `MigrationRunner.apply` carries no `if (rebuild)`
+ * branch — the two namespaces are distinct subclasses, not flags on one path.
+ */
+export declare class MigrationRunnerCore {
+    protected readonly crowi: Crowi;
+    protected readonly opts: ReturnType<typeof resolveOptions>;
+    private readonly ctx;
+    protected abortRequested: boolean;
+    private sigintHandler;
+    constructor(crowi: Crowi, options?: RunnerOptions);
+    /** True once a SIGINT has been received; long stages should wind down. */
+    get aborted(): boolean;
+    /** The shared per-run context handed to migration / rebuild callbacks. */
+    get context(): MigrationContext;
+    get concurrency(): number;
+    /**
+     * Install a SIGINT handler so an in-progress run can stop between
+     * stages / units instead of leaving Mongo in an arbitrary state. Returns
+     * a disposer; safe to call when no handler is desired (tests pass none).
+     */
+    installSigintHandler(): () => void;
+    private removeSigintHandler;
+    /**
+     * Run a bounded-concurrency map over `items`, respecting the SIGINT abort
+     * flag (stops scheduling new work once aborted). Exposed so a stage's `fn`
+     * or a rebuild task can fan out per-document work through the shared
+     * concurrency limiter.
+     */
+    mapBounded<T>(items: readonly T[], worker: (item: T, index: number) => Promise<void>): Promise<{
+        processed: number;
+        interrupted: boolean;
+    }>;
+}
+/**
+ * The `migrate`-namespace runner. Adds the §6.2 reconciliation rules and the
+ * `migrationApplications` audit-log append on top of the shared core. The
+ * `rebuild` namespace does NOT extend this — it rides the core directly so it
+ * stays free of any applied/pending semantics (§8.5).
+ */
+export declare class MigrationRunner extends MigrationRunnerCore {
+    /** Cheap pending probe. Never writes; safe to call on every boot (§4.2.1). */
+    isPending(def: MigrationDefinition): Promise<boolean>;
+    /** Rich, optional report for `plan`. Returns null when the migration has no `detect`. */
+    detect(def: MigrationDefinition): Promise<DetectReport | null>;
+    /**
+     * Apply a single migration through the framework's reconciliation rules
+     * (§6.2): inspection (`isPending`) is the source of truth; the recorded
+     * state only affects which `result` label we append.
+     *
+     *  - pending + no record    → run → `applied`
+     *  - pending + applied      → re-run (warn) → `re-applied`
+     *  - not pending + no record→ `detected-clean`
+     *  - not pending + applied  → no-op (consistent), no new record
+     *
+     * Appends one `migrationApplications` row per run (except the consistent
+     * no-op case). `dryRun` runs `detect`/probe only and records nothing.
+     */
+    apply(def: MigrationDefinition): Promise<MigrationRunOutcome>;
+    private recordApplication;
+}
+export {};