@alneas/eaos-server 0.0.0-stage → 0.2.0

package/dist/lifecycle-engine/index.d.ts

@@ -0,0 +1,1497 @@
+import { DataContract, DataContractCatalog } from '@alneas/eaos-core/contracts/data-contracts';
+export * from '@alneas/eaos-core/contracts/data-contracts';
+export { assertDataContractBinding, assertJsonDocumentContracts, collectSchemaMigrations, createJsonDocumentAssertion, dataContractTables, resolveDataContracts } from '@alneas/eaos-core/contracts/data-contracts';
+
+/**
+ * Hash-bound replacement of exact historical database migrations by equivalent baseline DDL.
+ *
+ * @see createDataContractBaseline for canonical integration usage.
+ */
+interface DataContractBaseline {
+    /**
+     * Baseline discriminator; currently 1.
+     */
+    format: 1;
+    /**
+     * Canonical contract release whose fully applied history is replaced.
+     */
+    source: DataContract;
+    /**
+     * Newer release retaining schema but using one database-scoped baseline migration.
+     */
+    target: DataContract;
+    /**
+     * Ordered historical migration IDs, positions and checksums requiring exact ledger matches.
+     */
+    replaces: {
+        /**
+         * Original immutable migration ID replaced by the baseline.
+         */
+        id: string;
+        /**
+         * Original zero-based migration position.
+         */
+        position: number;
+        /**
+         * Canonical original migration definition digest.
+         */
+        checksum: string;
+    }[];
+    /**
+     * Canonical digest of format/source/target/replaces.
+     */
+    hash: string;
+}
+/**
+ * Builds a newer single-migration contract release and hashes the exact historical migrations it replaces.
+ *
+ * Final DDL comes from a schema compiler or an isolated database introspector, never concatenation.
+ * @param source - Valid source contract with nonempty database-scoped migration history.
+ * @param version - Valid semver strictly newer than source.version.
+ * @param sql - Compiler/introspector-generated complete baseline DDL covering exactly the original dialect set.
+ * @returns Source/target contract snapshots, replacement migration checksums and integrity hash.
+ * @throws Error for nonnewer version, tenant-scoped/empty history, changed dialect set or invalid source/target contracts.
+ *
+ * @remarks
+ * Read-only; the host must establish final DDL equivalence using a schema compiler or isolated introspector. SQL is not concatenated or executed here.
+ *
+ * @example
+ * ```typescript
+ * import { createDataContractBaseline, type DataContract } from '@alneas/eaos-server/lifecycle-engine';
+ * export function reviewBaseline(source: DataContract, version: string, sql: DataContract['migrations'][number]['sql']) { return createDataContractBaseline(source, version, sql); }
+ * ```
+ */
+declare function createDataContractBaseline(source: DataContract, version: string, sql: DataContract['migrations'][number]['sql']): DataContractBaseline;
+/**
+ * Replaces a completely applied exact contract history with its reviewed baseline ledger record without running DDL.
+ *
+ * Rebase only a completely applied exact history. This function never executes DDL.
+ * @param store - Durable cross-process exclusive lifecycle store.
+ * @param databaseId - Physical database ledger identity whose contract history is rebased.
+ * @param baseline - Unmodified baseline created by createDataContractBaseline.
+ * @param options - Expected ledger revision and optional all-instance quiesce callback, required when affected consumers are active.
+ * @returns Baseline hash, next revision, count of replaced records and ddlExecuted=false.
+ * @throws Rejects integrity mismatch, stale revision, partial/dirty history, incompatible installed consumer range, absent drain or propagated store/quiesce failures.
+ *
+ * @remarks
+ * Runs under the store lock, archives old migration history and disables affected live consumers. Host drain happens before the final atomic state write; external drain may have occurred even if that write fails. No schema or data migration is executed.
+ *
+ * @example
+ * ```typescript
+ * import { rebaseDataContractBaseline, type DataContractBaseline, type LifecycleStore } from '@alneas/eaos-server/lifecycle-engine';
+ * export function rebaseReviewed(store: LifecycleStore, databaseId: string, baseline: DataContractBaseline, options: Parameters<typeof rebaseDataContractBaseline>[3]) { return rebaseDataContractBaseline(store, databaseId, baseline, options); }
+ * ```
+ */
+declare function rebaseDataContractBaseline(store: LifecycleStore, databaseId: string, baseline: DataContractBaseline, options: {
+    /**
+     * Exact current ledger revision reviewed by the caller; mismatch rejects before mutation.
+     */
+    expectedRevision: number;
+    /** Host drains all instances before disabling the affected live consumers. */
+    quiesce?: (input: {
+        /**
+         * Exact physical database identity whose live consumers must drain.
+         */
+        databaseId: string;
+        /**
+         * Distinct affected feature IDs consuming the rebased contract.
+         */
+        pluginIds: string[];
+    }) => Promise<void>;
+}): Promise<{
+    baselineHash: string;
+    revision: number;
+    rebased: number;
+    ddlExecuted: false;
+}>;
+
+/**
+ * Installed server package version used as the default lifecycle compatibility version.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+declare const FRAMEWORK_VERSION: string;
+/**
+ * Supported SQL dialects used to select reviewed migration statements.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+type Dialect = 'sqlite' | 'oracle' | 'postgres';
+
+/**
+ * Opaque physical database placement and shared/dedicated tenant scope.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface BackendTarget {
+    /**
+     * Stable execution backend ID; lifecycle plans reject identity changes under an existing ID.
+     */
+    id: string;
+    /**
+     * Opaque physical database identity shared by aliases of the same database; never a DSN.
+     */
+    databaseId: string;
+    /**
+     * SQL dialect required by this database and migration history.
+     */
+    dialect: Dialect;
+    /**
+     * Shared permits tenant isolation within one database; dedicated binds one tenant.
+     */
+    mode: 'shared' | 'dedicated';
+    /**
+     * Required concrete tenant for dedicated mode and forbidden for shared mode.
+     */
+    tenantId?: string;
+}
+/**
+ * Immutable reviewed migration statements scoped to a physical database or one tenant.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface PluginMigration {
+    /**
+     * Stable unique migration ID whose applied definition must never be rewritten.
+     */
+    id: string;
+    /**
+     * Database runs once per physical database; tenant runs once per tenant.
+     */
+    scope: 'database' | 'tenant';
+    /**
+     * Dialect-to-ordered-statements map; the target dialect must have nonempty statements.
+     */
+    sql: Partial<Record<Dialect, string[]>>;
+}
+/**
+ * Trusted release definition with feature dependencies, schema requirements and immutable migrations.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecyclePlugin {
+    /**
+     * Registered feature identifier, up to 128 letters/digits/underscore/hyphen characters starting alphanumeric.
+     */
+    id: string;
+    /**
+     * Valid semantic release version; changed contents require a version bump.
+     */
+    version: string;
+    /**
+     * Valid semver range for compatible framework versions.
+     */
+    framework: string;
+    /**
+     * Optional feature ID to semver range dependencies installed/enabled as a closure.
+     */
+    dependencies?: Record<string, string>;
+    /**
+     * Optional canonical data contract ranges; never installs or enables feature plugins.
+     *
+     * Storage dependencies do not install or enable a feature plugin.
+     */
+    schemaDependencies?: Record<string, string>;
+    /**
+     * Optional canonical releases supplied by a data package; duplicate IDs must agree exactly.
+     *
+     * Canonical contract releases supplied by the data package, not inline table copies.
+     */
+    schemaContracts?: DataContract[];
+    /**
+     * Append-only reviewed plugin migrations; contract-backed plugins must put DDL in data contracts instead.
+     *
+     * Immutable, reviewed migrations generated from the plugin's schema; never rewrite applied IDs.
+     */
+    migrations: PluginMigration[];
+    /**
+     * Optional nonsecret declarative host requirements; absence causes no infrastructure work.
+     *
+     * Declarative, host-defined resource requirements. No secrets. Absence means no infrastructure changes.
+     */
+    infrastructure?: Record<string, unknown>;
+}
+/**
+ * Lifecycle change to installation or tenant activation; disable/uninstall retain business data.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+type Operation = 'install' | 'update' | 'enable' | 'disable' | 'uninstall';
+/**
+ * Concrete lifecycle operation scoped to one registered backend and verified tenant.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecycleRequest {
+    /**
+     * Requested install/update/enable/disable/uninstall transition.
+     */
+    operation: Operation;
+    /**
+     * Registered plugin ID, or bundle ID for bundle planning.
+     */
+    pluginId: string;
+    /**
+     * Registered execution backend ID.
+     */
+    backendId: string;
+    /**
+     * Verified concrete tenant; must match dedicated backend scope.
+     */
+    tenantId: string;
+}
+/**
+ * Durable per-database/tenant migration progress and immutable definition checksum.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface MigrationRecord {
+    /**
+     * Physical database on which the migration executes.
+     */
+    databaseId: string;
+    /**
+     * Plugin or canonical data-contract migration identity.
+     */
+    pluginId: string;
+    /**
+     * Immutable migration definition ID.
+     */
+    migrationId: string;
+    /**
+     * Zero-based position in the append-only migration history.
+     */
+    position: number;
+    /**
+     * Concrete tenant for tenant-scoped work, or null for database scope.
+     */
+    tenantId: string | null;
+    /**
+     * Canonical definition digest used to detect rewritten applied SQL.
+     */
+    checksum: string;
+    /**
+     * Running/applied/failed progress; running and failed require reconciliation before planning further changes.
+     */
+    status: 'running' | 'applied' | 'failed';
+}
+/**
+ * Registered release snapshot and progress stored for one backend/plugin.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface Installation {
+    /**
+     * Copied trusted plugin release installed on this backend.
+     */
+    release: LifecyclePlugin;
+    /**
+     * Canonical digest of the release snapshot.
+     */
+    digest: string;
+    /**
+     * Installing/installed/failed progress; noninstalled records require reconciliation.
+     */
+    status: 'installing' | 'installed' | 'failed';
+}
+/**
+ * Durable platform tenant metadata independent of business schemas.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecyclePlatformTenant {
+    /**
+     * Stable concrete tenant ID.
+     */
+    id: string;
+    /**
+     * Public tenant display name.
+     */
+    name: string;
+    /**
+     * Whether platform tenant admission is enabled; membership remains host-owned.
+     */
+    active: boolean;
+    /**
+     * Configured tenant lookup domains; domain mapping alone never proves membership.
+     */
+    domains: readonly string[];
+    /**
+     * Tenant creation timestamp.
+     */
+    createdAt: string;
+    /**
+     * Latest metadata update timestamp.
+     */
+    updatedAt: string;
+}
+/**
+ * Durable tenant-to-backend routing assignment with optimistic routing revision.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecyclePlatformPlacement {
+    /**
+     * Verified tenant whose traffic is routed.
+     */
+    tenantId: string;
+    /**
+     * Opaque configured backend receiving traffic.
+     */
+    backendId: string;
+    /**
+     * Nonnegative revision used to track routing changes.
+     */
+    routingRevision: number;
+    /**
+     * Timestamp of the recorded routing switch.
+     */
+    changedAt: string;
+}
+/**
+ * Nonsecret descriptive metadata for an existing backend.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecyclePlatformBackendMetadata {
+    /**
+     * Optional public display label.
+     */
+    label?: string;
+    /**
+     * Optional provider descriptor; never credentials or DSNs.
+     */
+    provider?: string;
+    /**
+     * Optional declared host capability names, not permission grants.
+     */
+    capabilities?: readonly string[];
+}
+/**
+ * Persisted migration progress including uncertainty, failure, reconciliation and rollback states.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+type LifecyclePlatformMigrationStatus = 'planned' | 'running' | 'verified' | 'cutover' | 'failed' | 'reconciling' | 'rolled-back';
+/**
+ * Durable migration execution, verification and reconciliation evidence.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecyclePlatformMigrationRecord {
+    /**
+     * Current progress; reconciling represents uncertain execution outcomes.
+     */
+    status: LifecyclePlatformMigrationStatus;
+    /**
+     * Optional identity claiming the host migration execution.
+     */
+    executionId?: string;
+    /**
+     * Optional host-reported verification matching the migration plan.
+     */
+    verification?: BackendMigrationVerificationReport;
+    /**
+     * Optional source-retaining cutover receipt.
+     */
+    cutover?: BackendMigrationCutover;
+    /**
+     * Optional failure message and occurrence timestamp; exclude secrets.
+     */
+    error?: {
+        /**
+         * Nonsecret failure description retained for operator reconciliation.
+         */
+        message: string;
+        /**
+         * Timestamp at which the error was recorded.
+         */
+        occurredAt: string;
+    };
+    /**
+     * Timestamp of the latest migration-state change.
+     */
+    updatedAt: string;
+    /**
+     * Optional original migration ID when this is a rollback execution.
+     */
+    rollbackOf?: string;
+    /**
+     * Optional reviewed reverse plan associated with this migration.
+     */
+    rollbackPlanId?: string;
+}
+/**
+ * Platform-owned tenant, backend and migration control maps stored with the lifecycle ledger.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecyclePlatformState {
+    /**
+     * Tenant records indexed by tenant ID.
+     */
+    tenants: Record<string, LifecyclePlatformTenant>;
+    /**
+     * Current routing assignments indexed by tenant ID.
+     */
+    placements: Record<string, LifecyclePlatformPlacement>;
+    /**
+     * Nonsecret backend labels/provider capabilities indexed by backend ID.
+     */
+    backendMetadata: Record<string, LifecyclePlatformBackendMetadata>;
+    /**
+     * Reviewed backend migration plans indexed by migration ID.
+     */
+    migrationPlans: Record<string, BackendMigrationPlan>;
+    /**
+     * Execution/reconciliation records indexed by migration ID.
+     */
+    migrationRecords: Record<string, LifecyclePlatformMigrationRecord>;
+}
+/**
+ * Versioned durable control ledger for plugin readiness, schema history and platform placement.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecycleState {
+    /**
+     * Optional archived exact histories replaced by reviewed baselines.
+     */
+    baselineHistory?: Record<string, {
+        /**
+         * Exact archived baseline integrity hash.
+         */
+        hash: string;
+        /**
+         * Original canonical contract release retained for historical evidence.
+         */
+        source: DataContract;
+        /**
+         * Archived exact applied migration receipts.
+         */
+        migrations: Record<string, MigrationRecord>;
+    }>;
+    /**
+     * Persistent ledger discriminator; currently 1.
+     */
+    format: 1;
+    /**
+     * Nonnegative safe integer incremented on persisted lifecycle changes.
+     */
+    revision: number;
+    /**
+     * Opaque backend target definitions indexed by backend ID.
+     */
+    backends: Record<string, BackendTarget>;
+    /**
+     * Release snapshots indexed by JSON [backendId, pluginId].
+     */
+    installations: Record<string, Installation>;
+    /**
+     * Requested tenant activation records indexed by JSON [backendId, tenantId, pluginId]; effective readiness is checked separately.
+     */
+    activations: Record<string, {
+        /**
+         * Registered execution backend owning this activation.
+         */
+        backendId: string;
+        /**
+         * Concrete verified tenant owning this activation.
+         */
+        tenantId: string;
+        /**
+         * Registered feature ID requested for activation.
+         */
+        pluginId: string;
+        /**
+         * Canonical release or infrastructure definition digest.
+         */
+        digest: string;
+        /**
+         * Requested activation flag; effective readiness also requires matching installed digests and dependencies.
+         */
+        enabled: boolean;
+    }>;
+    /**
+     * Progress indexed by JSON [databaseId, migrationIdentity, migrationId, tenantId-or-*].
+     */
+    migrations: Record<string, MigrationRecord>;
+    /**
+     * Infrastructure digests/progress indexed by JSON [backendId, pluginId].
+     */
+    infrastructure: Record<string, {
+        /**
+         * Canonical release or infrastructure definition digest.
+         */
+        digest: string;
+        /**
+         * Persisted installing/installed/failed or running/applied/failed progress, according to this ledger map.
+         */
+        status: 'running' | 'applied' | 'failed';
+    }>;
+    /**
+     * Tenant/control-plane metadata and backend migration evidence.
+     */
+    platform: LifecyclePlatformState;
+    /**
+     * Optional canonical contract installation records indexed by JSON [databaseId, contractId].
+     */
+    dataContracts?: Record<string, {
+        /**
+         * Canonical schema contract release bound by its stored digest.
+         */
+        contract: DataContract;
+        /**
+         * Canonical release or infrastructure definition digest.
+         */
+        digest: string;
+        /**
+         * Persisted installing/installed/failed or running/applied/failed progress, according to this ledger map.
+         */
+        status: 'installing' | 'installed' | 'failed';
+    }>;
+}
+/**
+ * Atomic lifecycle snapshot access made available inside the host's exclusive lock.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecycleWriter {
+    /**
+     * Read the currently committed ledger snapshot; must not expose uncommitted writes.
+     * @returns The currently committed atomic ledger snapshot.
+     * @throws Host adapter or callback failures reject the returned Promise; side effects may already be partially complete.
+     
+     * @example
+     * ```typescript
+     * import type { LifecycleStore } from '@alneas/eaos-server/lifecycle-engine';
+     * export async function readLocked(store: LifecycleStore) {
+     *   return store.withLock(async writer => writer.read());
+     * }
+     * ```
+     */
+    read(): Promise<LifecycleState>;
+    /**
+     * Atomically persist the complete next snapshot; resolve only after durable completion.
+     * @param state - Complete next ledger snapshot with updated revision and control metadata.
+     * @returns Resolves without a value after the complete snapshot is durably committed.
+     * @throws Host adapter or callback failures reject the returned Promise; side effects may already be partially complete.
+     
+     * @example
+     * ```typescript
+     * import type { LifecycleStore } from '@alneas/eaos-server/lifecycle-engine';
+     * export async function persistReviewedRevision(store: LifecycleStore) {
+     *   await store.withLock(async writer => {
+     *     const state = await writer.read();
+     *     // Domain changes belong in the same reviewed writer callback.
+     *     state.revision += 1;
+     *     await writer.write(state);
+     *   });
+     * }
+     * ```
+     */
+    write(state: LifecycleState): Promise<void>;
+}
+/**
+ * Durable lifecycle reads and cross-process exclusive writer coordination.
+ *
+ *
+ * withLock must exclude every other writer, across processes. Reads must observe atomic committed snapshots.
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecycleStore extends Pick<LifecycleWriter, 'read'> {
+    /**
+     * Exclude every competing writer across processes and hold the lock until the async callback settles; release on success or failure.
+     * @param fn - Async work invoked only while holding exclusive writer ownership; receives atomic read/write capabilities.
+     * @typeParam T - Result resolved by the exclusive-lock callback.
+     * @returns The callback result after its lock is released; the lock is also released on failure.
+     * @throws Host adapter or callback failures reject the returned Promise; side effects may already be partially complete.
+     
+     * @example
+     * ```typescript
+     * import type { LifecycleStore } from '@alneas/eaos-server/lifecycle-engine';
+     * export async function snapshot(store: LifecycleStore) {
+     *   return store.withLock(async writer => writer.read());
+     * }
+     * ```
+     */
+    withLock<T>(fn: (writer: LifecycleWriter) => Promise<T>): Promise<T>;
+}
+/**
+ * Planned migration ledger identity and ordered SQL to execute on one physical target.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface MigrationStep {
+    /**
+     * Exact ledger map key for this migration and scope.
+     */
+    key: string;
+    /**
+     * Initial running migration receipt with immutable checksum.
+     */
+    record: MigrationRecord;
+    /**
+     * Reviewed target-dialect SQL executed in order by the host migrate adapter.
+     */
+    statements: string[];
+}
+/**
+ * Planned host infrastructure change bound to the release and backend digest.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface InfrastructureStep {
+    /**
+     * Infrastructure ledger key for backend/plugin.
+     */
+    key: string;
+    /**
+     * Canonical digest binding backend and plugin infrastructure configuration.
+     */
+    digest: string;
+    /**
+     * Trusted plugin release declaring infrastructure requirements.
+     */
+    plugin: LifecyclePlugin;
+    /**
+     * Exact target whose resources are previewed/applied.
+     */
+    backend: BackendTarget;
+}
+/**
+ * Reviewable hash-bound lifecycle transition generated against one ledger revision.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecyclePlan {
+    /**
+     * Plan discriminator; currently 1.
+     */
+    format: 1;
+    /**
+     * Canonical SHA-256 hash of all plan body fields.
+     */
+    id: string;
+    /**
+     * Ledger revision observed during planning; apply rejects stale plans.
+     */
+    revision: number;
+    /**
+     * Framework compatibility version used to resolve the plan.
+     */
+    frameworkVersion: string;
+    /**
+     * Original scoped operation request.
+     */
+    request: LifecycleRequest;
+    /**
+     * Snapshot of the exact immutable backend identity.
+     */
+    backend: BackendTarget;
+    /**
+     * Optional dependency-resolved canonical data contracts and table ownership.
+     */
+    dataCatalog?: DataContractCatalog;
+    /**
+     * Dependency-ordered trusted feature releases involved in the transition.
+     */
+    plugins: LifecyclePlugin[];
+    /**
+     * Ordered migration steps not already applied with matching checksums.
+     */
+    migrations: MigrationStep[];
+    /**
+     * Planned host infrastructure changes requiring the configured executor.
+     */
+    infrastructure: InfrastructureStep[];
+    /**
+     * Activation map keys disabled before disruptive changes.
+     */
+    deactivate: string[];
+    /**
+     * Configured executor identity, or null when none exists.
+     */
+    infrastructureProvider: string | null;
+    /**
+     * Always true; lifecycle uninstall never drops business data.
+     */
+    retainData: true;
+}
+/**
+ * Host-provided trusted release catalogs, durable lifecycle storage and side-effect adapters.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecycleProject {
+    /**
+     * Cross-process locked atomic durable lifecycle store.
+     */
+    store: LifecycleStore;
+    /**
+     * Trusted configured backend catalog; existing physical identities are immutable.
+     */
+    backends: BackendTarget[];
+    /**
+     * Trusted registered plugin releases; registration alone grants no tenant activation.
+     */
+    plugins: LifecyclePlugin[];
+    /**
+     * Optional canonical schema contract releases, also collected from plugin schemaContracts.
+     *
+       */
+    dataContracts?: readonly DataContract[];
+    /**
+     * Optional host aliases mapping bundle IDs to ordered registered feature IDs.
+     */
+    bundles?: Record<string, readonly string[]>;
+    /**
+     * Execute one reviewed migration step on the exact backend; reject failures so reconciliation state is recorded.
+     * @param step - Exact planned infrastructure step and target digest; do not reinterpret unreviewed settings.
+     * @param backend - Already-provisioned opaque backend declaration; never a connection string or credentials.
+     * @returns Resolves without a value after the reviewed host side effect completes.
+     * @throws Host adapter or callback failures reject the returned Promise; side effects may already be partially complete.
+     */
+    migrate: (step: MigrationStep, backend: BackendTarget) => Promise<void>;
+    /**
+     * Optional all-instance admission stop and active-work drain; required before upgrades affecting enabled activations.
+     *
+     * Stop admission and drain existing work on ALL affected backend instances before upgrades.
+     * @param activations - Host operation input bound to the scope described by this member.
+     * @returns Resolves without a value after the reviewed host side effect completes.
+     * @throws Host adapter or callback failures reject the returned Promise; side effects may already be partially complete.
+     */
+    quiesce?: (activations: LifecycleState['activations'][string][]) => Promise<void>;
+    /**
+     * Optional named host preview/apply capability; no credentials belong in declarative plugin settings.
+     */
+    infrastructure?: {
+        /**
+         * Stable nonsecret infrastructure-provider identity bound into reviewed plans.
+         */
+        identity: string;
+        /**
+         * Preview one exact infrastructure step; host must not claim application completion from preview.
+         * @param step - Exact reviewed infrastructure step for the configured backend.
+         * @returns Host preview information; no apply result is implied.
+         * @throws Rejects host adapter failures; effects may already have partially completed.
+         
+         * @example
+         * ```typescript
+         * import type { LifecycleProject, InfrastructureStep } from '@alneas/eaos-server/lifecycle-engine';
+         * export async function previewInfrastructure(project: LifecycleProject, step: InfrastructureStep) {
+         *   if (!project.infrastructure) throw new Error("Host infrastructure port required");
+         *   return project.infrastructure.preview(step);
+         * }
+         * ```
+         */
+        preview(step: InfrastructureStep): Promise<unknown>;
+        /**
+         * Apply one reviewed infrastructure step; errors leave reconciliation state and may follow partial external success.
+         * @param step - Exact reviewed infrastructure step for the configured backend.
+         * @returns Resolves without a value after host application completes.
+         * @throws Rejects host adapter failures; effects may already have partially completed.
+         
+         * @example
+         * ```typescript
+         * import type { LifecycleProject, InfrastructureStep } from '@alneas/eaos-server/lifecycle-engine';
+         * export async function applyInfrastructure(project: LifecycleProject, step: InfrastructureStep) {
+         *   if (!project.infrastructure) throw new Error("Host infrastructure port required");
+         *   await project.infrastructure.apply(step);
+         * }
+         * ```
+         */
+        apply(step: InfrastructureStep): Promise<void>;
+    };
+}
+/**
+ * One registered or historical plugin/backend pair with requested and effective tenant readiness.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecycleInventoryEntry {
+    /**
+     * Registered or historically recorded plugin ID.
+     */
+    pluginId: string;
+    /**
+     * Backend associated with the entry, or null when no backend is known.
+     */
+    backendId: string | null;
+    /**
+     * Whether this backend remains in the trusted runtime catalog.
+     */
+    backendConfigured: boolean;
+    /**
+     * Current registered code version, or null for orphaned history.
+     */
+    registeredVersion: string | null;
+    /**
+     * Stored installation version, or null before installation.
+     */
+    installedVersion: string | null;
+    /**
+     * Stored progress or not-installed.
+     */
+    installationStatus: Installation['status'] | 'not-installed';
+    /**
+     * Whether stored digest matches registered code, or null without installation.
+     */
+    releaseMatches: boolean | null;
+    /**
+     * Tenant requestedEnabled flags and effective enabled readiness results.
+     */
+    tenants: {
+        /**
+         * Concrete tenant whose activation is inspected.
+         */
+        tenantId: string;
+        /**
+         * Stored requested activation flag without readiness guarantees.
+         */
+        requestedEnabled: boolean;
+        /**
+         * Effective lifecycle readiness for the registered release and dependency closure.
+         */
+        enabled: boolean;
+    }[];
+}
+/**
+ * Read-only revision-bound plugin inventory including code-only and orphaned entries.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecycleInventory {
+    /**
+     * Inventory discriminator; currently 1.
+     */
+    format: 1;
+    /**
+     * Ledger snapshot revision inspected.
+     */
+    revision: number;
+    /**
+     * Framework compatibility version used for readiness.
+     */
+    frameworkVersion: string;
+    /**
+     * Deterministically ordered plugin/backend inventory entries, possibly empty.
+     */
+    plugins: LifecycleInventoryEntry[];
+}
+/**
+ * Reviewable ordered collection of member plans with projected sequential ledger revisions.
+ *
+ * @see PluginLifecycle for canonical integration usage.
+ */
+interface LifecycleBundlePlan {
+    /**
+     * Bundle discriminator; currently 1.
+     */
+    format: 1;
+    /**
+     * Canonical digest of bundle identity, operation and member plans.
+     */
+    id: string;
+    /**
+     * Registered host bundle alias.
+     */
+    bundleId: string;
+    /**
+     * Transition applied to every bundle member.
+     */
+    operation: Operation;
+    /**
+     * Dependency-compatible member order; reversed for disable/uninstall.
+     */
+    plans: LifecyclePlan[];
+}
+
+/**
+ * Creates independent empty platform tenant, placement and migration maps.
+ * @returns A new mutable platform-state object.
+ *
+ * @example
+ * ```typescript
+ * import { emptyLifecyclePlatformState } from '@alneas/eaos-server/lifecycle-engine';
+ * const platform = emptyLifecyclePlatformState();
+ * ```
+ */
+declare const emptyLifecyclePlatformState: () => LifecyclePlatformState;
+/**
+ * Creates an independent empty version-1 ledger with revision zero and platform state.
+ * @returns A new mutable LifecycleState with empty maps; no persistence is performed.
+ *
+ * @example
+ * ```typescript
+ * import { emptyLifecycleState } from '@alneas/eaos-server/lifecycle-engine';
+ * const state = emptyLifecycleState();
+ * ```
+ */
+declare const emptyLifecycleState: () => LifecycleState;
+/**
+ * Clones a historical ledger snapshot and fills missing platform maps without rewriting storage.
+ *
+ * Add fields introduced after the original snapshot format without rewriting old control rows on read.
+ * @param input - Historical state snapshot to normalize.
+ * @returns A structured clone with a complete platform object; unrelated state validation remains the caller's responsibility.
+ * @throws Error for nonobject input or malformed platform/maps; structuredClone errors propagate.
+ *
+ * @example
+ * ```typescript
+ * import { emptyLifecycleState, normalizeLifecycleState } from '@alneas/eaos-server/lifecycle-engine';
+ * const state = normalizeLifecycleState(emptyLifecycleState());
+ * ```
+ */
+declare function normalizeLifecycleState(input: LifecycleState): LifecycleState;
+/**
+ * Serializes JSON-compatible lifecycle values with recursively sorted object keys.
+ * @param value - JSON-serializable primitives, arrays or plain/null-prototype objects; avoid cycles and nonfinite numbers.
+ * @returns Deterministic JSON text; array order is preserved.
+ * @throws Error for unsupported values/prototypes, JSON serialization failure or recursive cycles.
+ *
+ * @remarks
+ * Uses JSON.stringify primitive semantics, including null for nonfinite numbers. It does not accept undefined/function/symbol values or class instances. Cyclic graphs are unsupported.
+ *
+ * @example
+ * ```typescript
+ * import { canonical } from '@alneas/eaos-server/lifecycle-engine';
+ * const serialized = canonical({ b: [2, 1], a: true });
+ * ```
+ */
+declare function canonical(value: unknown): string;
+/**
+ * Computes a lowercase SHA-256 digest of the canonical lifecycle JSON representation.
+ * @param value - Supported canonical JSON lifecycle configuration.
+ * @returns A 64-character lowercase hexadecimal digest.
+ * @throws Propagates canonical serialization errors for unsupported values.
+ *
+ * @remarks
+ * Requires Node crypto; the digest proves content identity, not authorization or authenticity.
+ *
+ * @example
+ * ```typescript
+ * import { lifecycleDigest } from '@alneas/eaos-server/lifecycle-engine';
+ * const digest = lifecycleDigest({ pluginId: 'reports', version: '1.0.0' });
+ * ```
+ */
+declare const lifecycleDigest: (value: unknown) => string;
+/**
+ * Plans and applies checksum-bound plugin/schema changes against an exclusively locked host ledger.
+ *
+ * @remarks
+ * Server runtime uses Node crypto and semver. The host provides durable cross-process locking, tenant authorization, SQL migration execution and any infrastructure/quiesce adapters. Installation never implies tenant enablement; disable/uninstall retain data. Migration/infrastructure failures persist reconciliation state, and DDL is not rolled back automatically.
+ *
+ * @example
+ * ```typescript
+ * import { PluginLifecycle, type LifecycleProject } from '@alneas/eaos-server/lifecycle-engine';
+ * export function connectLifecycle(project: LifecycleProject) { return new PluginLifecycle(project); }
+ * ```
+ */
+declare class PluginLifecycle {
+    private readonly project;
+    readonly frameworkVersion: string;
+    private readonly plugins;
+    private readonly backends;
+    private readonly contracts;
+    /**
+     * Validates and snapshots the registered plugin, backend, contract and bundle catalogs.
+     * @param project - Host lifecycle storage, trusted catalogs and execution adapters.
+     * @param frameworkVersion - Valid semver framework version; defaults to the installed package version.
+     * @throws Error for invalid/duplicate IDs, versions, migrations, conflicting schemas, unsupported backend configuration or unsatisfied contract dependencies.
+     *
+     * @example
+     * ```typescript
+     * import { PluginLifecycle, type LifecycleProject } from '@alneas/eaos-server/lifecycle-engine';
+     * export function connectLifecycle(project: LifecycleProject) { return new PluginLifecycle(project); }
+     * ```
+     */
+    constructor(project: LifecycleProject, frameworkVersion?: string);
+    private bundle;
+    /**
+     * Plans registered bundle members sequentially against a projected ledger state.
+     * @param request - Lifecycle request whose pluginId names a registered bundle.
+     * @returns A checksum-bound ordered bundle plan with each member's projected revision.
+     * @throws Rejects unknown bundle, invalid member request/state or propagated store failures.
+     *
+     * @remarks
+     * Disable/uninstall reverse bundle order. Planning executes no migrations or writes; projected revisions mirror member apply ordering.
+     *
+     * @example
+     * ```typescript
+     * import { PluginLifecycle, type LifecycleRequest } from '@alneas/eaos-server/lifecycle-engine';
+     * export function reviewBundle(lifecycle: PluginLifecycle, request: LifecycleRequest) { return lifecycle.planBundle(request); }
+     * ```
+     */
+    planBundle(request: LifecycleRequest): Promise<LifecycleBundlePlan>;
+    /**
+     * Advance the read-only state used while constructing sequential bundle plans.
+     * apply() performs these writes in the same order; mirroring them here keeps
+     * each plan's revision and dependency closure valid when applyBundle() runs.
+     */
+    private projectBundleState;
+    /**
+     * Validates a reviewed bundle plan and applies its member plans in sequence.
+     * @param bundlePlan - Unmodified checksum-bound bundle plan from planBundle.
+     * @returns Resolves without a value after every member apply completes.
+     * @throws Rejects modified/stale/misordered bundle plans, member apply failures and propagated host errors.
+     *
+     * @remarks
+     * Members acquire their own ledger locks. There is no all-or-nothing bundle transaction; earlier members remain applied if a later member fails. Replan/reconcile before retrying uncertain outcomes.
+     *
+     * @example
+     * ```typescript
+     * import { PluginLifecycle, type LifecycleBundlePlan } from '@alneas/eaos-server/lifecycle-engine';
+     * export function applyReviewedBundle(lifecycle: PluginLifecycle, plan: LifecycleBundlePlan) { return lifecycle.applyBundle(plan); }
+     * ```
+     */
+    applyBundle(bundlePlan: LifecycleBundlePlan): Promise<void>;
+    private release;
+    private order;
+    /**
+     * Resolves the canonical schema dependency catalog for registered feature plugins.
+     *
+     * Read-only complete schema inventory for the selected trusted feature catalog.
+     * @param pluginIds - Optional feature IDs; omitted includes all registered plugins, while an empty array selects none.
+     * @returns A JSON-cloned dependency-resolved DataContractCatalog.
+     * @throws Error for unknown/incompatible feature dependencies or invalid/conflicting contract requirements.
+     *
+     * @remarks
+     * Read-only; schema dependencies never install or enable feature plugins.
+     *
+     * @example
+     * ```typescript
+     * import { PluginLifecycle } from '@alneas/eaos-server/lifecycle-engine';
+     * export function schemas(lifecycle: PluginLifecycle) { return lifecycle.schemaCatalog(); }
+     * ```
+     */
+    schemaCatalog(pluginIds?: readonly string[]): DataContractCatalog;
+    private catalog;
+    private contractReady;
+    /** Contract ledger identities may retain a feature's historical name even
+     * when that feature no longer consumes the contract. Match the actual
+     * immutable migration, rather than only the current feature's catalog. */
+    private isContractMigration;
+    private target;
+    /**
+     * Creates a reviewable lifecycle plan from one current ledger snapshot without executing side effects.
+     * @param request - Concrete operation, registered plugin/backend and verified tenant; see LifecycleRequest.
+     * @returns A deterministic checksum-bound plan carrying the snapshot revision, dependency closure, migrations and retained-data policy.
+     * @throws Rejects invalid request/state, incompatible or missing dependencies, changed applied migrations, dirty ledger, unsupported dialect, tenant mismatch or propagated store failures.
+     *
+     * @remarks
+     * Planning is read-only but may become stale immediately. Backend physical identity is immutable. Updates require appended immutable migrations and compatible schema versions; installation and enablement are separate operations.
+     *
+     * @example
+     * ```typescript
+     * import { PluginLifecycle, type LifecycleRequest } from '@alneas/eaos-server/lifecycle-engine';
+     * export function review(lifecycle: PluginLifecycle, request: LifecycleRequest) { return lifecycle.plan(request); }
+     * ```
+     */
+    plan(request: LifecycleRequest): Promise<LifecyclePlan>;
+    private makePlan;
+    private dependsOn;
+    private ready;
+    /**
+     * Checks that a tenant activation and its entire registered dependency closure match ready ledger releases.
+     * @param backendId - Registered execution backend ID.
+     * @param tenantId - Verified concrete tenant ID.
+     * @param pluginId - Registered feature ID to check.
+     * @returns True only when matching installation, migrations, infrastructure and activation digests are all ready; false for missing/incompatible readiness.
+     * @throws Rejects malformed IDs/state, unknown or mismatched backend/tenant and store failures.
+     *
+     * @remarks
+     * Read-only admission check; a later state change can revoke access. Host must still enforce current tenant/resource authorization.
+     *
+     * @example
+     * ```typescript
+     * import { PluginLifecycle } from '@alneas/eaos-server/lifecycle-engine';
+     * export function admitted(lifecycle: PluginLifecycle, backendId: string, tenantId: string, pluginId: string) { return lifecycle.isEnabled(backendId, tenantId, pluginId); }
+     * ```
+     */
+    isEnabled(backendId: string, tenantId: string, pluginId: string): Promise<boolean>;
+    private enabledInState;
+    /**
+     * Reads inventory including registered uninstalled code and orphaned historical installations.
+     *
+     * One read-only control-state snapshot; includes orphaned installation records and registered, uninstalled code.
+     * @param options - Optional backendId and tenantId filters; omitted returns all known inventory.
+     * @returns A revision-bound inventory with effective enabled state distinct from requested activation.
+     * @throws Rejects invalid filter IDs, unknown backend, corrupt installation/activation records, dedicated tenant mismatch or store failure.
+     *
+     * @remarks
+     * Performs one ledger read without writes. Dedicated backends for another tenant are omitted unless explicitly requested, in which case the request rejects.
+     *
+     * @example
+     * ```typescript
+     * import { PluginLifecycle } from '@alneas/eaos-server/lifecycle-engine';
+     * export function inventory(lifecycle: PluginLifecycle) { return lifecycle.list(); }
+     * ```
+     */
+    list(options?: {
+        /**
+         * Optional exact backend filter; unknown backends reject.
+         */
+        backendId?: string;
+        /**
+         * Optional concrete tenant filter; dedicated backend scope must match.
+         */
+        tenantId?: string;
+    }): Promise<LifecycleInventory>;
+    /**
+     * Runs a host callback only after the current plugin dependency closure passes lifecycle admission.
+     * @typeParam T - Value resolved by the admitted callback.
+     * @param backendId - Registered backend ID.
+     * @param tenantId - Verified concrete tenant ID.
+     * @param pluginId - Feature plugin ID.
+     * @param callback - Async work invoked once after admission; must enforce tenant/resource authorization itself.
+     * @returns The callback result without cloning.
+     * @throws Rejects inactive plugin, lifecycle/store validation failure or callback rejection.
+     *
+     * @remarks
+     * The admission check does not hold a lock or pin activation throughout callback execution. Host quiesce/drain and live authorization remain required.
+     *
+     * @example
+     * ```typescript
+     * import { PluginLifecycle } from '@alneas/eaos-server/lifecycle-engine';
+     * export function runAdmitted<T>(lifecycle: PluginLifecycle, backendId: string, tenantId: string, pluginId: string, work: () => Promise<T>) { return lifecycle.run(backendId, tenantId, pluginId, work); }
+     * ```
+     */
+    run<T>(backendId: string, tenantId: string, pluginId: string, callback: () => Promise<T>): Promise<T>;
+    /**
+     * Checks plan freshness and invokes host infrastructure previews without applying ledger changes.
+     * @param plan - Unmodified lifecycle plan to preview.
+     * @returns Preview results in infrastructure-step order, or an empty array when no infrastructure is needed.
+     * @throws Rejects stale/modified plan, missing infrastructure adapter or propagated plan/preview errors.
+     *
+     * @remarks
+     * Infrastructure previews run concurrently through Promise.all. Host preview adapters own any external read/preview effects; this method executes no migrations.
+     *
+     * @example
+     * ```typescript
+     * import { PluginLifecycle, type LifecyclePlan } from '@alneas/eaos-server/lifecycle-engine';
+     * export function preview(lifecycle: PluginLifecycle, plan: LifecyclePlan) { return lifecycle.preview(plan); }
+     * ```
+     */
+    preview(plan: LifecyclePlan): Promise<unknown[]>;
+    /**
+     * Revalidates and executes a reviewed lifecycle plan while holding the host's exclusive ledger lock.
+     * @param plan - Unmodified plan bound to the current ledger revision and registered configuration.
+     * @returns Resolves without a value after ledger updates and requested side effects complete.
+     * @throws Rejects stale/modified plan, missing executors/quiesce, reconciliation conflicts or host store, migration, infrastructure or drain failures.
+     *
+     * @remarks
+     * Before upgrade side effects, affected activations are disabled durably and all-instance quiesce is required. Infrastructure/migration running/applied/failed receipts are persisted separately. Errors can follow partial external success; no automatic rollback/retry occurs. Uninstall retains business data and migration history.
+     *
+     * @example
+     * ```typescript
+     * import { PluginLifecycle, type LifecyclePlan } from '@alneas/eaos-server/lifecycle-engine';
+     * export function applyReviewed(lifecycle: PluginLifecycle, plan: LifecyclePlan) { return lifecycle.apply(plan); }
+     * ```
+     */
+    apply(plan: LifecyclePlan): Promise<void>;
+}
+
+/**
+ * Explicit complete fleet or nonempty concrete tenant selection for a reviewed data move.
+ *
+ * @see planBackendMigration for canonical integration usage.
+ */
+type BackendMigrationScope = {
+    /**
+     * Scope discriminator: all-tenants includes the fleet; tenants names a concrete bounded selection.
+     */
+    kind: 'all-tenants';
+} | {
+    /**
+     * Scope discriminator: all-tenants includes the fleet; tenants names a concrete bounded selection.
+     */
+    kind: 'tenants';
+    /**
+     * Nonempty distinct concrete tenant IDs; dedicated endpoint tenants must be included.
+     */
+    tenantIds: readonly string[];
+};
+/**
+ * Operator-reviewed source/target database move with bounded scope and reason.
+ *
+ * @see planBackendMigration for canonical integration usage.
+ */
+interface BackendMigrationRequest {
+    /**
+     * Nonblank stable migration identity, up to 256 characters.
+     */
+    migrationId: string;
+    /**
+     * Existing backend whose data remains retained.
+     */
+    source: BackendTarget;
+    /**
+     * Different backend and physical database identity.
+     */
+    target: BackendTarget;
+    /**
+     * All tenants or nonempty unique explicit tenant IDs; dedicated endpoints require their tenant in explicit scope.
+     */
+    scope: BackendMigrationScope;
+    /**
+     * Nonempty unique registered-style feature IDs covered by the move.
+     */
+    pluginIds: readonly string[];
+    /**
+     * Parseable request timestamp.
+     */
+    requestedAt: string;
+    /**
+     * Nonblank reviewed operator reason, at most 1024 characters.
+     */
+    reason: string;
+}
+/**
+ * Deterministic five-phase non-destructive data migration plan.
+ *
+ * @see planBackendMigration for canonical integration usage.
+ */
+interface BackendMigrationPlan {
+    /**
+     * Plan discriminator; currently 1.
+     */
+    format: 1;
+    /**
+     * Canonical digest of the normalized request and phase/safety flags.
+     */
+    id: string;
+    /**
+     * Cloned request with sorted plugin and explicit tenant IDs.
+     */
+    request: BackendMigrationRequest;
+    /**
+     * Ordered prepare/copy/verify/cutover/retain-source execution phases.
+     */
+    phases: readonly ['prepare', 'copy', 'verify', 'cutover', 'retain-source'];
+    /**
+     * Always true; the host must drain affected execution before switching.
+     */
+    requiresQuiesce: true;
+    /**
+     * Always true; source data must remain available.
+     */
+    retainSourceData: true;
+    /**
+     * Always false; dropping source data is outside this plan.
+     */
+    destructiveOperations: false;
+}
+/**
+ * Host-reported match for one tenant/plugin copy at observed revisions.
+ *
+ * @see planBackendMigration for canonical integration usage.
+ */
+interface BackendMigrationVerification {
+    /**
+     * Concrete verified tenant covered by the plan.
+     */
+    tenantId: string;
+    /**
+     * Planned feature whose records were compared.
+     */
+    pluginId: string;
+    /**
+     * Nonnegative safe revision observed at source.
+     */
+    sourceRevision: number;
+    /**
+     * Nonnegative safe revision observed at target; not required to numerically equal source.
+     */
+    targetRevision: number;
+    /**
+     * True only when the host comparison passed; validator does not perform the comparison.
+     */
+    matched: boolean;
+}
+/**
+ * Host verification evidence bound to a reviewed source/target migration.
+ *
+ * @see planBackendMigration for canonical integration usage.
+ */
+interface BackendMigrationVerificationReport {
+    /**
+     * Plan request migration identity.
+     */
+    migrationId: string;
+    /**
+     * Exact source backend identity.
+     */
+    sourceBackendId: string;
+    /**
+     * Exact target backend identity.
+     */
+    targetBackendId: string;
+    /**
+     * Parseable verification timestamp.
+     */
+    checkedAt: string;
+    /**
+     * Nonempty matched in-scope record reports; host must establish exhaustive coverage.
+     */
+    records: readonly BackendMigrationVerification[];
+    /**
+     * Host declaration that verification passed; must be true for acceptance.
+     */
+    passed: boolean;
+}
+/**
+ * Host-reported routing switch retaining the original database for recovery.
+ *
+ * @see planBackendMigration for canonical integration usage.
+ */
+interface BackendMigrationCutover {
+    /**
+     * Plan migration identity.
+     */
+    migrationId: string;
+    /**
+     * Exact reviewed target backend.
+     */
+    targetBackendId: string;
+    /**
+     * Nonnegative safe routing revision after cutover.
+     */
+    routingRevision: number;
+    /**
+     * Parseable routing-switch timestamp.
+     */
+    cutoverAt: string;
+    /**
+     * Must be true; destructive source cleanup is outside this contract.
+     */
+    sourceRetained: true;
+}
+/**
+ * Host-owned migration phases operating on real adapters and retained source storage.
+ *
+ * @see planBackendMigration for canonical integration usage.
+ */
+interface BackendMigrationExecutor {
+    /**
+     * Provision/adopt the reviewed target and establish quiescence without deleting source data.
+     * @param plan - Reviewed unmodified backend migration plan; host must preserve quiescence and source data.
+     * @returns Resolves without a value after target preparation and required quiescence.
+     * @throws Host adapter or callback failures reject the returned Promise; side effects may already be partially complete.
+     
+     * @example
+     * ```typescript
+     * import type { BackendMigrationExecutor, BackendMigrationPlan } from '@alneas/eaos-server/lifecycle-engine';
+     * export async function prepareReviewed(executor: BackendMigrationExecutor, plan: BackendMigrationPlan) {
+     *   // The host approves exact targets and serializes migration writers.
+     *   await executor.prepare(plan);
+     * }
+     * ```
+     */
+    prepare(plan: BackendMigrationPlan): Promise<void>;
+    /**
+     * Copy the scoped tenant/plugin data into the target and retain source state.
+     * @param plan - Reviewed unmodified backend migration plan; host must preserve quiescence and source data.
+     * @returns Resolves without a value after the scoped copy completes, with source retained.
+     * @throws Host adapter or callback failures reject the returned Promise; side effects may already be partially complete.
+     
+     * @example
+     * ```typescript
+     * import type { BackendMigrationExecutor, BackendMigrationPlan } from '@alneas/eaos-server/lifecycle-engine';
+     * export async function copyReviewed(executor: BackendMigrationExecutor, plan: BackendMigrationPlan) {
+     *   // The host approves exact targets and serializes migration writers.
+     *   await executor.copy(plan);
+     * }
+     * ```
+     */
+    copy(plan: BackendMigrationPlan): Promise<void>;
+    /**
+     * Produce nonempty exhaustive host match evidence for the plan's scope.
+     * @param plan - Reviewed unmodified backend migration plan; host must preserve quiescence and source data.
+     * @returns The host verification report; caller must check it against the reviewed plan.
+     * @throws Host adapter or callback failures reject the returned Promise; side effects may already be partially complete.
+     
+     * @example
+     * ```typescript
+     * import type { BackendMigrationExecutor, BackendMigrationPlan } from '@alneas/eaos-server/lifecycle-engine';
+     * export async function verifyReviewed(executor: BackendMigrationExecutor, plan: BackendMigrationPlan) {
+     *   // The host approves exact targets and serializes migration writers.
+     *   return executor.verify(plan);
+     * }
+     * ```
+     */
+    verify(plan: BackendMigrationPlan): Promise<BackendMigrationVerificationReport>;
+    /**
+     * Switch routing only after valid verification, retaining source and returning a cutover receipt.
+     * @param plan - Reviewed unmodified backend migration plan; host must preserve quiescence and source data.
+     * @param verification - Matching passed host verification report; establish complete copy coverage before cutover.
+     * @returns A source-retaining routing cutover receipt after accepted verification.
+     * @throws Host adapter or callback failures reject the returned Promise; side effects may already be partially complete.
+     
+     * @example
+     * ```typescript
+     * import type { BackendMigrationExecutor, BackendMigrationPlan, BackendMigrationVerificationReport } from '@alneas/eaos-server/lifecycle-engine';
+     * export async function cutoverReviewed(executor: BackendMigrationExecutor, plan: BackendMigrationPlan, verification: BackendMigrationVerificationReport) {
+     *   // Supply current, successful evidence for this exact reviewed plan.
+     *   return executor.cutover(plan, verification);
+     * }
+     * ```
+     */
+    cutover(plan: BackendMigrationPlan, verification: BackendMigrationVerificationReport): Promise<BackendMigrationCutover>;
+}
+/**
+ * Creates a deterministic source-retaining migration plan without touching either database.
+ *
+ * Create a reviewable fleet/tenant data-migration plan without touching either backend.
+ * @param request - Reviewed distinct physical source/target backends, concrete tenant scope, nonempty unique plugin IDs, timestamp and reason.
+ * @returns A shallow-frozen plan with sorted cloned scopes/plugin IDs and five ordered phases.
+ * @throws Error for malformed request, same source/target identity, invalid scope or dedicated-tenant mismatch.
+ *
+ * @remarks
+ * Dedicated backend tenants must appear in explicit tenant scope. No executor, lock, provisioning, copy or cutover runs during planning; host must implement quiescence.
+ *
+ * @example
+ * ```typescript
+ * import { planBackendMigration } from '@alneas/eaos-server/lifecycle-engine/backend-migration';
+ * const plan = planBackendMigration({ migrationId: 'move-1', source: { id: 'old', databaseId: 'db-old', dialect: 'sqlite', mode: 'shared' }, target: { id: 'new', databaseId: 'db-new', dialect: 'postgres', mode: 'shared' }, scope: { kind: 'tenants', tenantIds: ['sample'] }, pluginIds: ['reports'], requestedAt: '2026-01-01T00:00:00Z', reason: 'Reviewed backend move' });
+ * ```
+ */
+declare function planBackendMigration(request: BackendMigrationRequest): BackendMigrationPlan;
+/**
+ * Checks that a reported migration verification matches its plan and contains only matched in-scope records.
+ * @param plan - Reviewed backend migration plan.
+ * @param report - Host report claiming passed verification for the plan's source and target.
+ * @returns The original report when accepted; it is neither cloned nor independently measured.
+ * @throws Error for mismatched identities, invalid timestamp/revisions, out-of-scope records or unpassed/unmatched evidence.
+ *
+ * @remarks
+ * Validates nonempty records and nonnegative revisions, but does not prove exhaustive tenant/plugin coverage or equal source/target revision numbers. The host owns verification completeness and truth.
+ *
+ * @example
+ * ```typescript
+ * import { assertBackendMigrationVerification, type BackendMigrationPlan, type BackendMigrationVerificationReport } from '@alneas/eaos-server/lifecycle-engine/backend-migration';
+ * export function inspectVerification(plan: BackendMigrationPlan, report: BackendMigrationVerificationReport) { return assertBackendMigrationVerification(plan, report); }
+ * ```
+ */
+declare function assertBackendMigrationVerification(plan: BackendMigrationPlan, report: BackendMigrationVerificationReport): BackendMigrationVerificationReport;
+/**
+ * Validates matching verification and a source-retaining cutover receipt for the target backend.
+ * @param plan - Reviewed backend migration plan.
+ * @param report - Passed host verification matching the plan.
+ * @param cutover - Host routing receipt with nonnegative routing revision and parseable cutover timestamp.
+ * @returns The original cutover object; no routing mutation occurs.
+ * @throws Error for invalid verification, mismatched target/migration, missing source-retention claim or invalid revision/time.
+ *
+ * @remarks
+ * This is evidence shape validation, not independent copy verification or authority to switch a tenant.
+ *
+ * @example
+ * ```typescript
+ * import { assertBackendMigrationCutover, type BackendMigrationPlan, type BackendMigrationVerificationReport, type BackendMigrationCutover } from '@alneas/eaos-server/lifecycle-engine/backend-migration';
+ * export function inspectCutover(plan: BackendMigrationPlan, report: BackendMigrationVerificationReport, receipt: BackendMigrationCutover) { return assertBackendMigrationCutover(plan, report, receipt); }
+ * ```
+ */
+declare function assertBackendMigrationCutover(plan: BackendMigrationPlan, report: BackendMigrationVerificationReport, cutover: BackendMigrationCutover): BackendMigrationCutover;
+
+export { FRAMEWORK_VERSION, PluginLifecycle, assertBackendMigrationCutover, assertBackendMigrationVerification, canonical, createDataContractBaseline, emptyLifecyclePlatformState, emptyLifecycleState, lifecycleDigest, normalizeLifecycleState, planBackendMigration, rebaseDataContractBaseline };
+export type { BackendMigrationCutover, BackendMigrationExecutor, BackendMigrationPlan, BackendMigrationRequest, BackendMigrationScope, BackendMigrationVerification, BackendMigrationVerificationReport, BackendTarget, DataContractBaseline, Dialect, InfrastructureStep, Installation, LifecycleBundlePlan, LifecycleInventory, LifecycleInventoryEntry, LifecyclePlan, LifecyclePlatformBackendMetadata, LifecyclePlatformMigrationRecord, LifecyclePlatformMigrationStatus, LifecyclePlatformPlacement, LifecyclePlatformState, LifecyclePlatformTenant, LifecyclePlugin, LifecycleProject, LifecycleRequest, LifecycleState, LifecycleStore, LifecycleWriter, MigrationRecord, MigrationStep, Operation, PluginMigration };