@ankhorage/infra 4.1.12 → 5.1.0

package/src/features/environment-lifecycle/application/use-cases/downInfraEnvironmentAsync.ts

@@ -0,0 +1,65 @@
+import type { InfraDiagnostic, InfraOutput, InfraOwnedResource } from '@ankhorage/contracts/infra';
+
+import type {
+  InfraDownOperationResult,
+  InfraOperationRequest,
+  InfraOrchestrationDependencies,
+} from '../../../../types/infraOrchestration.js';
+import { appendInfraFailure } from '../../utils/appendInfraFailure.js';
+import { createInfraLedger } from '../../utils/createInfraLedger.js';
+import { retainUnchangedAdapterOutputs } from '../../utils/retainUnchangedAdapterOutputs.js';
+import { retainUnchangedAdapterResources } from '../../utils/retainUnchangedAdapterResources.js';
+import { prepareInfraOperationAsync } from './prepareInfraOperationAsync.js';
+
+/*** Reversibly suspend services and runtime while retaining compute and persistent data. */
+export async function downInfraEnvironmentAsync(
+  request: InfraOperationRequest,
+  dependencies: InfraOrchestrationDependencies,
+): Promise<InfraDownOperationResult> {
+  const prepared = await prepareInfraOperationAsync(request, 'down', dependencies);
+  if (!prepared.ok) return prepared;
+  const diagnostics: InfraDiagnostic[] = [...prepared.diagnostics];
+  const resources: InfraOwnedResource[] = [];
+  const outputs: InfraOutput[] = [];
+  const replacedAdapters = new Set<string>();
+  for (const service of [...prepared.value.adapters.services].reverse()) {
+    if (service.suspendAsync === undefined) continue;
+    const result = await service.suspendAsync(prepared.value.context);
+    if (!result.ok) return appendInfraFailure(diagnostics, result);
+    replacedAdapters.add(service.descriptor.id);
+    resources.push(...result.value.resources);
+    outputs.push(...result.value.outputs);
+    diagnostics.push(...result.diagnostics);
+  }
+  if (prepared.value.runtimeDesired.targets.length > 0) {
+    const runtime = await prepared.value.adapters.runtime.suspendAsync(
+      prepared.value.context,
+      prepared.value.runtimeDesired,
+    );
+    if (!runtime.ok) return appendInfraFailure(diagnostics, runtime);
+    replacedAdapters.add(prepared.value.adapters.runtime.descriptor.id);
+    resources.push(...runtime.value.resources);
+    outputs.push(...runtime.value.outputs);
+    diagnostics.push(...runtime.diagnostics);
+  }
+  const previousResources = request.previous?.resources ?? [];
+  const previousOutputs = request.previous?.outputs ?? [];
+  return {
+    ok: true,
+    value: {
+      environment: prepared.value.environment.id,
+      ledger: createInfraLedger({
+        projectId: request.projectId,
+        environment: prepared.value.environment.id,
+        targets:
+          prepared.value.compute.targets.length > 0
+            ? prepared.value.compute.targets
+            : (request.previous?.targets ?? []),
+        resources: retainUnchangedAdapterResources(previousResources, resources, replacedAdapters),
+        outputs: retainUnchangedAdapterOutputs(previousOutputs, outputs, replacedAdapters),
+        previous: request.previous,
+      }),
+    },
+    diagnostics,
+  };
+}

package/src/features/environment-lifecycle/application/use-cases/generateInfraEnvironmentAsync.ts

@@ -0,0 +1,51 @@
+import type { InfraDiagnostic } from '@ankhorage/contracts/infra';
+
+import type {
+  InfraGenerateOperationResult,
+  InfraOperationRequest,
+  InfraOrchestrationDependencies,
+} from '../../../../types/infraOrchestration.js';
+import { appendInfraFailure } from '../../utils/appendInfraFailure.js';
+import { createInfraLedger } from '../../utils/createInfraLedger.js';
+import { mergeInfraOutputs } from '../../utils/mergeInfraOutputs.js';
+import { mergeInfraResources } from '../../utils/mergeInfraResources.js';
+import { prepareInfraOperationAsync } from './prepareInfraOperationAsync.js';
+
+/*** Generate deterministic review artifacts without mutating local or remote infrastructure. */
+export async function generateInfraEnvironmentAsync(
+  request: InfraOperationRequest,
+  dependencies: InfraOrchestrationDependencies,
+): Promise<InfraGenerateOperationResult> {
+  const prepared = await prepareInfraOperationAsync(request, 'generate', dependencies);
+  if (!prepared.ok) return prepared;
+  const diagnostics: InfraDiagnostic[] = [...prepared.diagnostics];
+  const { runtime } = prepared.value.adapters;
+  const artifacts =
+    runtime.generateAsync === undefined || prepared.value.runtimeDesired.targets.length === 0
+      ? { ok: true as const, value: [], diagnostics: [] }
+      : await runtime.generateAsync(prepared.value.context, prepared.value.runtimeDesired);
+  if (!artifacts.ok) return appendInfraFailure(diagnostics, artifacts);
+  diagnostics.push(...artifacts.diagnostics);
+  return {
+    ok: true,
+    value: {
+      environment: prepared.value.environment.id,
+      artifacts: artifacts.value,
+      ledger: createInfraLedger({
+        projectId: request.projectId,
+        environment: prepared.value.environment.id,
+        targets:
+          prepared.value.compute.targets.length > 0
+            ? prepared.value.compute.targets
+            : (request.previous?.targets ?? []),
+        resources: mergeInfraResources(
+          request.previous?.resources ?? [],
+          prepared.value.compute.resources,
+        ),
+        outputs: mergeInfraOutputs(request.previous?.outputs ?? [], prepared.value.compute.outputs),
+        artifacts: artifacts.value,
+      }),
+    },
+    diagnostics,
+  };
+}

package/src/features/environment-lifecycle/application/use-cases/getInfraEnvironmentOutputs.ts

@@ -0,0 +1,41 @@
+import type {
+  InfraOperationRequest,
+  InfraOutputsOperationResult,
+} from '../../../../types/infraOrchestration.js';
+import { resolveInfraEnvironment } from '../../domain/resolveInfraEnvironment.js';
+
+/*** Return only safe serialized public outputs and secret references from the canonical ledger. */
+export function getInfraEnvironmentOutputs(
+  request: InfraOperationRequest,
+): InfraOutputsOperationResult {
+  const environment = resolveInfraEnvironment({
+    manifest: request.manifest,
+    environment: request.environment,
+    operation: 'outputs',
+  });
+  if (!environment.ok) return environment;
+  if (
+    request.previous !== undefined &&
+    (request.previous.projectId !== request.projectId ||
+      request.previous.environment !== environment.value.id)
+  ) {
+    return {
+      ok: false,
+      diagnostics: [
+        {
+          severity: 'error',
+          code: 'infra-ledger-scope-mismatch',
+          message: 'Stored Infra state does not belong to the selected project and environment.',
+        },
+      ],
+    };
+  }
+  return {
+    ok: true,
+    value: {
+      environment: environment.value.id,
+      outputs: request.previous?.outputs ?? [],
+    },
+    diagnostics: environment.diagnostics,
+  };
+}

package/src/features/environment-lifecycle/application/use-cases/planInfraEnvironmentAsync.ts

@@ -0,0 +1,67 @@
+import type { InfraDiagnostic, InfraPlanAction } from '@ankhorage/contracts/infra';
+
+import type {
+  InfraOperationRequest,
+  InfraOrchestrationDependencies,
+  InfraPlanOperationResult,
+} from '../../../../types/infraOrchestration.js';
+import { orderInfraPlanActions } from '../../domain/orderInfraPlanActions.js';
+import { appendInfraFailure } from '../../utils/appendInfraFailure.js';
+import { prepareInfraOperationAsync } from './prepareInfraOperationAsync.js';
+
+/*** Aggregate a side-effect-free dependency-ordered plan from all selected adapters. */
+export async function planInfraEnvironmentAsync(
+  request: InfraOperationRequest,
+  dependencies: InfraOrchestrationDependencies,
+): Promise<InfraPlanOperationResult> {
+  const prepared = await prepareInfraOperationAsync(request, 'plan', dependencies);
+  if (!prepared.ok) return prepared;
+  const diagnostics: InfraDiagnostic[] = [...prepared.diagnostics];
+  const actions: InfraPlanAction[] = [];
+  const compute = await prepared.value.adapters.compute.planAsync(
+    prepared.value.context,
+    prepared.value.environment.desired.deployment.compute,
+  );
+  if (!compute.ok) return appendInfraFailure(diagnostics, compute);
+  actions.push(...compute.value);
+  diagnostics.push(...compute.diagnostics);
+  if (prepared.value.runtimeDesired.targets.length === 0) {
+    actions.push({
+      owner: {
+        projectId: request.projectId,
+        environment: prepared.value.environment.id,
+        adapter: prepared.value.adapters.runtime.descriptor.id,
+        resourceId: 'runtime',
+      },
+      operation: 'create',
+      impact: 'none',
+      detail: 'Runtime planning is deferred until the planned compute target exists.',
+      dependsOn: compute.value.map(({ owner }) => owner),
+    });
+  } else {
+    const runtime = await prepared.value.adapters.runtime.planAsync(
+      prepared.value.context,
+      prepared.value.runtimeDesired,
+    );
+    if (!runtime.ok) return appendInfraFailure(diagnostics, runtime);
+    actions.push(...runtime.value);
+    diagnostics.push(...runtime.diagnostics);
+  }
+  for (const service of prepared.value.adapters.services) {
+    const plan = await service.planAsync(prepared.value.context);
+    if (!plan.ok) return appendInfraFailure(diagnostics, plan);
+    actions.push(...plan.value);
+    diagnostics.push(...plan.diagnostics);
+  }
+  const ordered = orderInfraPlanActions(actions);
+  if (!ordered.ok) return appendInfraFailure(diagnostics, ordered);
+  return {
+    ok: true,
+    value: {
+      projectId: request.projectId,
+      environment: prepared.value.environment.id,
+      actions: ordered.value,
+    },
+    diagnostics,
+  };
+}

package/src/features/environment-lifecycle/application/use-cases/prepareInfraOperationAsync.ts

@@ -0,0 +1,137 @@
+import type { InfraDiagnostic, InfraResult } from '@ankhorage/contracts/infra';
+
+import type {
+  InfraOperationRequest,
+  InfraOrchestrationDependencies,
+  PreparedInfraOperation,
+} from '../../../../types/infraOrchestration.js';
+import { resolveInfraEnvironment } from '../../domain/resolveInfraEnvironment.js';
+import { appendInfraFailure } from '../../utils/appendInfraFailure.js';
+import { createInfraExecutionContext } from '../../utils/createInfraExecutionContext.js';
+import { collectInfraWorkloadsAsync } from './collectInfraWorkloadsAsync.js';
+import { resolveInfraAdaptersAsync } from './resolveInfraAdaptersAsync.js';
+import { validateInfraAdaptersAsync } from './validateInfraAdaptersAsync.js';
+
+/*** Resolve and validate one operation without creating, updating or deleting infrastructure. */
+export async function prepareInfraOperationAsync(
+  request: InfraOperationRequest,
+  operation: 'validate' | 'plan' | 'generate' | 'status' | 'outputs' | 'down' | 'destroy',
+  dependencies: InfraOrchestrationDependencies,
+): Promise<InfraResult<PreparedInfraOperation>> {
+  const diagnostics: InfraDiagnostic[] = [];
+  const environment = resolveInfraEnvironment({
+    manifest: request.manifest,
+    environment: request.environment,
+    operation,
+  });
+  if (!environment.ok) return environment;
+  diagnostics.push(...environment.diagnostics);
+  if (
+    request.previous !== undefined &&
+    request.previousDesired !== undefined &&
+    !hasSameProviderSelection(request.previousDesired, environment.value.desired)
+  ) {
+    return {
+      ok: false,
+      diagnostics: [
+        ...diagnostics,
+        {
+          severity: 'error',
+          code: 'infra-provider-selection-changed',
+          message:
+            'Stored Infra resources use another provider selection. Destroy that environment before applying the new selection.',
+        },
+      ],
+    };
+  }
+  const adapters = await resolveInfraAdaptersAsync(
+    environment.value.desired,
+    dependencies.adapterResolver,
+  );
+  if (!adapters.ok) return appendInfraFailure(diagnostics, adapters);
+  diagnostics.push(...adapters.diagnostics);
+  const context = createInfraExecutionContext(request, environment.value, dependencies);
+  const validation = await validateInfraAdaptersAsync(context, adapters.value);
+  if (!validation.ok) return appendInfraFailure(diagnostics, validation);
+  diagnostics.push(...validation.diagnostics);
+  const workloads = await collectInfraWorkloadsAsync(context, adapters.value.services);
+  if (!workloads.ok) return appendInfraFailure(diagnostics, workloads);
+  diagnostics.push(...workloads.diagnostics);
+  const compute = await adapters.value.compute.inspectAsync(
+    context,
+    environment.value.desired.deployment.compute,
+  );
+  if (!compute.ok) return appendInfraFailure(diagnostics, compute);
+  diagnostics.push(...compute.diagnostics);
+  const runtimeDesired = {
+    selection: environment.value.desired.deployment.runtime,
+    targets:
+      compute.value.targets.length > 0
+        ? compute.value.targets
+        : (request.previous?.targets ?? compute.value.targets),
+    workloads: [...(environment.value.desired.workloads ?? []), ...workloads.value],
+    availableOutputs: mergeOutputs(request.previous?.outputs ?? [], compute.value.outputs),
+  };
+  if (runtimeDesired.targets.length === 0) {
+    diagnostics.push({
+      severity: 'info',
+      code: 'infra-runtime-target-deferred',
+      message: 'Runtime validation is deferred until compute exposes a portable target.',
+    });
+  } else {
+    const runtime = await adapters.value.runtime.validateAsync(context, runtimeDesired);
+    if (!runtime.ok) return appendInfraFailure(diagnostics, runtime);
+    diagnostics.push(...runtime.diagnostics);
+  }
+  return {
+    ok: true,
+    value: {
+      environment: environment.value,
+      context,
+      adapters: adapters.value,
+      compute: compute.value,
+      runtimeDesired,
+    },
+    diagnostics,
+  };
+}
+
+/*** Compare provider identity only; configuration changes remain normal in-place reconciliation. */
+function hasSameProviderSelection(
+  previous: PreparedInfraOperation['environment']['desired'],
+  current: PreparedInfraOperation['environment']['desired'],
+): boolean {
+  return providerSelection(previous).join('\0') === providerSelection(current).join('\0');
+}
+
+/*** Read the closed provider slots in stable capability order. */
+function providerSelection(
+  desired: PreparedInfraOperation['environment']['desired'],
+): readonly (string | undefined)[] {
+  return [
+    desired.deployment.compute.provider,
+    desired.deployment.runtime.provider,
+    desired.database?.provider,
+    desired.objectStorage?.provider,
+    desired.auth?.provider,
+    desired.authz?.provider,
+    desired.secretStore?.provider,
+  ];
+}
+
+/*** Prefer freshly inspected outputs while preserving unrelated safe prior values. */
+function mergeOutputs(
+  previous: PreparedInfraOperation['runtimeDesired']['availableOutputs'],
+  current: PreparedInfraOperation['runtimeDesired']['availableOutputs'],
+): PreparedInfraOperation['runtimeDesired']['availableOutputs'] {
+  const currentKeys = new Set(current.map(outputKey));
+  return [...previous.filter((output) => !currentKeys.has(outputKey(output))), ...current];
+}
+
+/*** Create one stable public-or-secret output identity without reading its value. */
+function outputKey(
+  output: PreparedInfraOperation['runtimeDesired']['availableOutputs'][number],
+): string {
+  const { owner } = output;
+  return `${owner.projectId}\0${owner.environment}\0${owner.adapter}\0${owner.resourceId}\0${output.name}`;
+}

package/src/features/environment-lifecycle/application/use-cases/resolveInfraAdaptersAsync.ts

@@ -0,0 +1,257 @@
+import {
+  INFRA_ADAPTER_CATALOG,
+  type InfraAdapterDescriptor,
+  type InfraComputeAdapter,
+  type InfraDiagnostic,
+  type InfraEnvironmentSpec,
+  type InfraResult,
+  type InfraRuntimeAdapter,
+  type InfraServiceAdapter,
+  isInfraAdapterDescriptor,
+  validateInfraAdapterSelection,
+} from '@ankhorage/contracts/infra';
+
+import type { ResolvedInfraAdapters } from '../../../../types/infraOrchestration.js';
+import type {
+  InfraAdapterPackageModule,
+  InfraAdapterPackageResolver,
+} from '../ports/outbound/infraAdapterPackage.js';
+
+/*** Resolve exactly the selected provider packages and validate their public adapter boundaries. */
+export async function resolveInfraAdaptersAsync(
+  environment: InfraEnvironmentSpec,
+  resolver: InfraAdapterPackageResolver,
+): Promise<InfraResult<ResolvedInfraAdapters>> {
+  const entries = getSelectedCatalogEntries(environment);
+  const modules = await Promise.all(
+    entries.map(async (entry) => loadModuleAsync(entry.package, resolver)),
+  );
+  const loadingDiagnostics = modules.flatMap((result) => result.diagnostics);
+  if (loadingDiagnostics.length > 0) return { ok: false, diagnostics: loadingDiagnostics };
+  const loaded = modules.flatMap((result) => (result.ok ? [result.value] : []));
+  const selection = validateInfraAdapterSelection(
+    environment,
+    loaded.map(({ infraAdapterDescriptor }) => infraAdapterDescriptor),
+  );
+  if (!selection.ok) return selection;
+  const instantiated = instantiateModules(loaded);
+  if (!instantiated.ok) return instantiated;
+  const instances = instantiated.value;
+  const compute = instances.find(isComputeAdapter);
+  const runtime = instances.find(isRuntimeAdapter);
+  const services = instances.filter(isServiceAdapter);
+  const diagnostics = validateInstances(compute, runtime, services, selection.value);
+  return diagnostics.length > 0 || compute === undefined || runtime === undefined
+    ? { ok: false, diagnostics }
+    : {
+        ok: true,
+        value: { compute, runtime, services: orderServiceAdapters(services) },
+        diagnostics: [],
+      };
+}
+
+/*** Order services by selected capability dependencies while preserving catalog order for peers. */
+function orderServiceAdapters(
+  services: readonly InfraServiceAdapter[],
+): readonly InfraServiceAdapter[] {
+  const pending = [...services];
+  const ordered: InfraServiceAdapter[] = [];
+  const provided = new Set<string>(['compute', 'runtime', 'workloads', 'networking']);
+  while (pending.length > 0) {
+    const index = pending.findIndex((service) =>
+      service.descriptor.dependencies.every(
+        (dependency) =>
+          provided.has(dependency) ||
+          !services.some(({ descriptor }) => hasCapability(descriptor, dependency)),
+      ),
+    );
+    if (index < 0) return services;
+    const [service] = pending.splice(index, 1);
+    if (service === undefined) return services;
+    ordered.push(service);
+    for (const capability of service.descriptor.capabilities) provided.add(capability);
+  }
+  return ordered;
+}
+
+/*** Compare catalog capability values across descriptor union members. */
+function hasCapability(descriptor: InfraAdapterDescriptor, capability: string): boolean {
+  return (descriptor.capabilities as readonly string[]).includes(capability);
+}
+
+/*** Invoke selected factories safely and require their instances to match the module descriptor. */
+function instantiateModules(
+  modules: readonly InfraAdapterPackageModule[],
+): InfraResult<readonly unknown[]> {
+  const instances: unknown[] = [];
+  const diagnostics: InfraDiagnostic[] = [];
+  for (const module of modules) {
+    try {
+      const instance = module.createInfraAdapter();
+      if (!isAdapterForDescriptor(instance, module.infraAdapterDescriptor)) {
+        diagnostics.push(
+          instanceDiagnostic(
+            module.infraAdapterDescriptor.id,
+            `Selected adapter factory for ${module.infraAdapterDescriptor.package} returned a mismatched lifecycle implementation.`,
+          ),
+        );
+      } else instances.push(instance);
+    } catch {
+      diagnostics.push(
+        instanceDiagnostic(
+          module.infraAdapterDescriptor.id,
+          `Selected adapter factory for ${module.infraAdapterDescriptor.package} could not be created.`,
+        ),
+      );
+    }
+  }
+  return diagnostics.length > 0
+    ? { ok: false, diagnostics }
+    : { ok: true, value: instances, diagnostics: [] };
+}
+
+/*** Select each configured adapter once, including multi-capability service providers. */
+function getSelectedCatalogEntries(environment: InfraEnvironmentSpec) {
+  const ids = new Set([
+    environment.deployment.compute.provider,
+    environment.deployment.runtime.provider,
+    environment.database?.provider,
+    environment.objectStorage?.provider,
+    environment.auth?.provider,
+    environment.authz?.provider,
+    environment.secretStore?.provider,
+  ]);
+  return Object.values(INFRA_ADAPTER_CATALOG).filter((entry) => ids.has(entry.id));
+}
+
+/*** Convert module-resolution errors into provider-safe diagnostics without importing alternatives. */
+async function loadModuleAsync(
+  packageName: string,
+  resolver: InfraAdapterPackageResolver,
+): Promise<InfraResult<InfraAdapterPackageModule>> {
+  try {
+    const loaded: unknown = await resolver.loadAsync(packageName);
+    return isInfraAdapterPackageModule(loaded)
+      ? { ok: true, value: loaded, diagnostics: [] }
+      : adapterFailure(
+          'infra-adapter-module-invalid',
+          `Selected adapter package ${packageName} does not export its canonical descriptor and factory.`,
+        );
+  } catch {
+    return adapterFailure(
+      'infra-adapter-package-unavailable',
+      `Selected adapter package ${packageName} could not be loaded.`,
+    );
+  }
+}
+
+/*** Validate the runtime shape of a dynamically loaded provider package. */
+function isInfraAdapterPackageModule(value: unknown): value is InfraAdapterPackageModule {
+  return (
+    isRecord(value) &&
+    isInfraAdapterDescriptor(value.infraAdapterDescriptor) &&
+    typeof value.createInfraAdapter === 'function'
+  );
+}
+
+/*** Validate one compute adapter instance without trusting a dynamic module cast. */
+function isComputeAdapter(value: unknown): value is InfraComputeAdapter {
+  return hasAdapterMethods(value, 'compute', [
+    'validateAsync',
+    'inspectAsync',
+    'planAsync',
+    'ensureAsync',
+    'statusAsync',
+    'destroyAsync',
+  ]);
+}
+
+/*** Validate one runtime adapter instance without trusting a dynamic module cast. */
+function isRuntimeAdapter(value: unknown): value is InfraRuntimeAdapter {
+  return hasAdapterMethods(value, 'runtime', [
+    'validateAsync',
+    'planAsync',
+    'ensureAsync',
+    'statusAsync',
+    'suspendAsync',
+    'destroyAsync',
+  ]);
+}
+
+/*** Validate one service adapter instance without trusting a dynamic module cast. */
+function isServiceAdapter(value: unknown): value is InfraServiceAdapter {
+  return hasAdapterMethods(value, 'service', [
+    'validateAsync',
+    'planAsync',
+    'desiredWorkloadsAsync',
+    'reconcileAsync',
+    'statusAsync',
+    'destroyAsync',
+  ]);
+}
+
+/*** Match a factory result to the exact descriptor selected from its module. */
+function isAdapterForDescriptor(value: unknown, expected: InfraAdapterDescriptor): boolean {
+  const validShape =
+    expected.kind === 'compute'
+      ? isComputeAdapter(value)
+      : expected.kind === 'runtime'
+        ? isRuntimeAdapter(value)
+        : isServiceAdapter(value);
+  return (
+    validShape &&
+    isRecord(value) &&
+    isInfraAdapterDescriptor(value.descriptor) &&
+    value.descriptor.id === expected.id &&
+    value.descriptor.package === expected.package
+  );
+}
+
+/*** Check a dynamic adapter descriptor kind and its required lifecycle methods. */
+function hasAdapterMethods(
+  value: unknown,
+  kind: InfraAdapterDescriptor['kind'],
+  methods: readonly string[],
+): boolean {
+  return (
+    isRecord(value) &&
+    isInfraAdapterDescriptor(value.descriptor) &&
+    value.descriptor.kind === kind &&
+    methods.every((method) => typeof Reflect.get(value, method) === 'function')
+  );
+}
+
+/*** Ensure factories returned exactly one matching compute/runtime adapter and every service. */
+function validateInstances(
+  compute: InfraComputeAdapter | undefined,
+  runtime: InfraRuntimeAdapter | undefined,
+  services: readonly InfraServiceAdapter[],
+  descriptors: readonly InfraAdapterDescriptor[],
+): readonly InfraDiagnostic[] {
+  const expectedServices = descriptors.filter(({ kind }) => kind === 'service').length;
+  const diagnostics: InfraDiagnostic[] = [];
+  if (compute === undefined)
+    diagnostics.push(instanceDiagnostic('compute', 'Selected compute adapter factory is invalid.'));
+  if (runtime === undefined)
+    diagnostics.push(instanceDiagnostic('runtime', 'Selected runtime adapter factory is invalid.'));
+  if (services.length !== expectedServices)
+    diagnostics.push(
+      instanceDiagnostic('service', 'A selected service adapter factory is invalid.'),
+    );
+  return diagnostics;
+}
+
+/*** Create an adapter-factory diagnostic without exposing module exception details. */
+function instanceDiagnostic(kind: string, message: string): InfraDiagnostic {
+  return { severity: 'error', code: `infra-${kind}-adapter-invalid`, message };
+}
+
+/*** Create a failed adapter resolution result. */
+function adapterFailure(code: string, message: string): InfraResult<never> {
+  return { ok: false, diagnostics: [{ severity: 'error', code, message }] };
+}
+
+/*** Narrow dynamically loaded module and adapter values. */
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === 'object' && value !== null;
+}