@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

[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

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

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); }

[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

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

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); }

[FUNCTION] `assertDataContractBinding`

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

[FUNCTION] `assertJsonDocumentContracts`

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

[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

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.

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.

[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

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.

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:

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:

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:

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:

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.

[INTERFACE] `BackendMigrationPlan`

Deterministic five-phase non-destructive data migration plan.

Imports: @alneas/eaos-server/lifecycle-engine, @alneas/eaos-server/lifecycle-engine/backend-migration.

Signature

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.

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.

[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

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.

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.

[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

type BackendMigrationScope = {
    kind: 'all-tenants';
} | {
    kind: 'tenants';
    tenantIds: readonly string[];
};

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

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.

[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

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.

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.

[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

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.

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.

[INTERFACE] `BackendTarget`

Opaque physical database placement and shared/dedicated tenant scope.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[FUNCTION] `canonical`

Serializes JSON-compatible lifecycle values with recursively sorted object keys.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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

import { canonical } from '@alneas/eaos-server/lifecycle-engine';
const serialized = canonical({ b: [2, 1], a: true });

[FUNCTION] `collectSchemaMigrations`

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

[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

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

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); }

[FUNCTION] `createJsonDocumentAssertion`

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

[INTERFACE] `DataContract`

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

[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

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.

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.

[INTERFACE] `DataContractBinding`

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

[INTERFACE] `DataContractCatalog`

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

[FUNCTION] `dataContractTables`

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

[TYPE] `Dialect`

Supported SQL dialects used to select reviewed migration statements.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

type Dialect = 'sqlite' | 'oracle' | 'postgres';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `emptyLifecyclePlatformState`

Creates independent empty platform tenant, placement and migration maps.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

declare const emptyLifecyclePlatformState: () => LifecyclePlatformState;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

LifecyclePlatformState

A new mutable platform-state object.

Example

import { emptyLifecyclePlatformState } from '@alneas/eaos-server/lifecycle-engine';
const platform = emptyLifecyclePlatformState();

[FUNCTION] `emptyLifecycleState`

Creates an independent empty version-1 ledger with revision zero and platform state.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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

import { emptyLifecycleState } from '@alneas/eaos-server/lifecycle-engine';
const state = emptyLifecycleState();

[CONSTANT] `FRAMEWORK_VERSION`

Installed server package version used as the default lifecycle compatibility version.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

declare const FRAMEWORK_VERSION: string;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `InfrastructureStep`

Planned host infrastructure change bound to the release and backend digest.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `Installation`

Registered release snapshot and progress stored for one backend/plugin.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `JsonDocumentContract`

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

[INTERFACE] `LifecycleBundlePlan`

Reviewable ordered collection of member plans with projected sequential ledger revisions.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[FUNCTION] `lifecycleDigest`

Computes a lowercase SHA-256 digest of the canonical lifecycle JSON representation.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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

import { lifecycleDigest } from '@alneas/eaos-server/lifecycle-engine';
const digest = lifecycleDigest({ pluginId: 'reports', version: '1.0.0' });

[INTERFACE] `LifecycleInventory`

Read-only revision-bound plugin inventory including code-only and orphaned entries.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `LifecycleInventoryEntry`

One registered or historical plugin/backend pair with requested and effective tenant readiness.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `LifecyclePlan`

Reviewable hash-bound lifecycle transition generated against one ledger revision.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `LifecyclePlatformBackendMetadata`

Nonsecret descriptive metadata for an existing backend.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `LifecyclePlatformMigrationRecord`

Durable migration execution, verification and reconciliation evidence.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[TYPE] `LifecyclePlatformMigrationStatus`

Persisted migration progress including uncertainty, failure, reconciliation and rollback states.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

type LifecyclePlatformMigrationStatus = 'planned' | 'running' | 'verified' | 'cutover' | 'failed' | 'reconciling' | 'rolled-back';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `LifecyclePlatformPlacement`

Durable tenant-to-backend routing assignment with optimistic routing revision.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `LifecyclePlatformState`

Platform-owned tenant, backend and migration control maps stored with the lifecycle ledger.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `LifecyclePlatformTenant`

Durable platform tenant metadata independent of business schemas.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `LifecyclePlugin`

Trusted release definition with feature dependencies, schema requirements and immutable migrations.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `LifecycleProject`

Host-provided trusted release catalogs, durable lifecycle storage and side-effect adapters.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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:

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:

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.

[INTERFACE] `LifecycleRequest`

Concrete lifecycle operation scoped to one registered backend and verified tenant.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `LifecycleState`

Versioned durable control ledger for plugin readiness, schema history and platform placement.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[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

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.

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:

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.

[INTERFACE] `LifecycleWriter`

Atomic lifecycle snapshot access made available inside the host’s exclusive lock.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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:

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:

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.

[INTERFACE] `MigrationRecord`

Durable per-database/tenant migration progress and immutable definition checksum.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[INTERFACE] `MigrationStep`

Planned migration ledger identity and ordered SQL to execute on one physical target.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[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

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

import { emptyLifecycleState, normalizeLifecycleState } from '@alneas/eaos-server/lifecycle-engine';
const state = normalizeLifecycleState(emptyLifecycleState());

[TYPE] `Operation`

Lifecycle change to installation or tenant activation; disable/uninstall retain business data.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

type Operation = 'install' | 'update' | 'enable' | 'disable' | 'uninstall';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[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

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

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' });

[CLASS] `PluginLifecycle`

Plans and applies checksum-bound plugin/schema changes against an exclusively locked host ledger.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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:

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:

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:

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:

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:

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:

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:

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:

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:

import { PluginLifecycle, type LifecyclePlan } from '@alneas/eaos-server/lifecycle-engine';
export function applyReviewed(lifecycle: PluginLifecycle, plan: LifecyclePlan) { return lifecycle.apply(plan); }

Example

import { PluginLifecycle, type LifecycleProject } from '@alneas/eaos-server/lifecycle-engine';
export function connectLifecycle(project: LifecycleProject) { return new PluginLifecycle(project); }

[INTERFACE] `PluginMigration`

Immutable reviewed migration statements scoped to a physical database or one tenant.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

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.

[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

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

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); }

[FUNCTION] `resolveDataContracts`

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

[INTERFACE] `SchemaMigrationSource`

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/lifecycle-engine.

Signature

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.

@alneas/eaos-server API

@alneas/eaos-server API

Public entrypoints

[FUNCTION] assertBackendMigrationCutover

Signature

Parameters

Returns

Remarks

Errors and rejections

Example

[FUNCTION] assertBackendMigrationVerification

Signature

Parameters

Returns

Remarks

Errors and rejections

Example

[FUNCTION] assertDataContractBinding

Signature

Parameters

Returns

Example

[FUNCTION] assertJsonDocumentContracts

Signature

Parameters

Returns

Example

[INTERFACE] BackendMigrationCutover

Signature

Parameters

Returns

See also

Public members

migrationId

targetBackendId

routingRevision

cutoverAt

sourceRetained

Example

[INTERFACE] BackendMigrationExecutor

Signature

Parameters

Returns

See also

Public members

prepare

Errors and rejections

copy

Errors and rejections

verify

Errors and rejections

cutover

Errors and rejections

Example

[INTERFACE] BackendMigrationPlan

Signature

Parameters

Returns

See also

Public members

format

id

request

phases

requiresQuiesce

retainSourceData

destructiveOperations

Example

[INTERFACE] BackendMigrationRequest

Signature

Parameters

Returns

See also

Public members

migrationId

source

target

scope

pluginIds

requestedAt

[FUNCTION] `assertBackendMigrationCutover`

[FUNCTION] `assertBackendMigrationVerification`

[FUNCTION] `assertDataContractBinding`

[FUNCTION] `assertJsonDocumentContracts`

[INTERFACE] `BackendMigrationCutover`

`migrationId`

`targetBackendId`

`routingRevision`

`cutoverAt`

`sourceRetained`

[INTERFACE] `BackendMigrationExecutor`

`prepare`

`copy`

`verify`

`cutover`

[INTERFACE] `BackendMigrationPlan`

`format`

`id`

`request`

`phases`

`requiresQuiesce`

`retainSourceData`

`destructiveOperations`

[INTERFACE] `BackendMigrationRequest`

`migrationId`

`source`

`target`

`scope`

`pluginIds`

`requestedAt`

`reason`

[TYPE] `BackendMigrationScope`

`kind`

`kind`

`tenantIds`

[INTERFACE] `BackendMigrationVerification`

`tenantId`

`pluginId`

`sourceRevision`

`targetRevision`

`matched`

[INTERFACE] `BackendMigrationVerificationReport`

`migrationId`

`sourceBackendId`

`targetBackendId`

`checkedAt`

`records`

`passed`

[INTERFACE] `BackendTarget`

`id`

`databaseId`

`dialect`

`mode`

`tenantId`

[FUNCTION] `canonical`

[FUNCTION] `collectSchemaMigrations`

[FUNCTION] `createDataContractBaseline`

[FUNCTION] `createJsonDocumentAssertion`