@alneas/eaos-server 0.0.0-stage → 0.2.0

package/docs/lifecycle/docs/api.md

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