@ankhorage/infra 4.1.12 → 5.1.0

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

@@ -0,0 +1,80 @@
+import type { InfraDiagnostic, InfraResourceStatus } from '@ankhorage/contracts/infra';
+
+import type {
+  InfraOperationRequest,
+  InfraOrchestrationDependencies,
+  InfraStatusOperationResult,
+} from '../../../../types/infraOrchestration.js';
+import { appendInfraFailure } from '../../utils/appendInfraFailure.js';
+import { prepareInfraOperationAsync } from './prepareInfraOperationAsync.js';
+
+/*** Aggregate provider-neutral compute, runtime and service status. */
+export async function statusInfraEnvironmentAsync(
+  request: InfraOperationRequest,
+  dependencies: InfraOrchestrationDependencies,
+): Promise<InfraStatusOperationResult> {
+  const prepared = await prepareInfraOperationAsync(request, 'status', dependencies);
+  if (!prepared.ok) return prepared;
+  const diagnostics: InfraDiagnostic[] = [...prepared.diagnostics];
+  const resources: InfraResourceStatus[] = [];
+  const compute = await prepared.value.adapters.compute.statusAsync(prepared.value.context);
+  if (!compute.ok) return appendInfraFailure(diagnostics, compute);
+  resources.push(...compute.value);
+  diagnostics.push(...compute.diagnostics);
+  if (prepared.value.runtimeDesired.targets.length === 0) {
+    resources.push({
+      owner: {
+        projectId: request.projectId,
+        environment: prepared.value.environment.id,
+        adapter: prepared.value.adapters.runtime.descriptor.id,
+        resourceId: 'runtime',
+      },
+      state: 'absent',
+      detail: 'Compute has not exposed a portable runtime target.',
+    });
+  } else {
+    const runtime = await prepared.value.adapters.runtime.statusAsync(
+      prepared.value.context,
+      prepared.value.runtimeDesired,
+    );
+    if (!runtime.ok) return appendInfraFailure(diagnostics, runtime);
+    resources.push(...runtime.value);
+    diagnostics.push(...runtime.diagnostics);
+  }
+  for (const service of prepared.value.adapters.services) {
+    const status = await service.statusAsync(prepared.value.context);
+    if (!status.ok) return appendInfraFailure(diagnostics, status);
+    resources.push(...status.value);
+    diagnostics.push(...status.diagnostics);
+  }
+  return {
+    ok: true,
+    value: {
+      projectId: request.projectId,
+      environment: prepared.value.environment.id,
+      state: aggregateInfraStatus(resources),
+      resources,
+    },
+    diagnostics,
+  };
+}
+
+/*** Select the most actionable canonical status, treating an empty environment as absent. */
+function aggregateInfraStatus(
+  resources: readonly InfraResourceStatus[],
+): InfraResourceStatus['state'] {
+  if (resources.length === 0) return 'absent';
+  const severity: readonly InfraResourceStatus['state'][] = [
+    'failed',
+    'degraded',
+    'pending',
+    'unknown',
+    'stopped',
+    'retained',
+    'absent',
+    'ready',
+  ];
+  return (
+    severity.find((state) => resources.some((resource) => resource.state === state)) ?? 'unknown'
+  );
+}

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

@@ -0,0 +1,126 @@
+import type {
+  InfraDiagnostic,
+  InfraExecutionContext,
+  InfraOutput,
+  InfraOwnedResource,
+  InfraResult,
+  InfraServiceAdapter,
+} from '@ankhorage/contracts/infra';
+
+import type {
+  InfraOrchestrationDependencies,
+  InfraUpOperationResult,
+  InfraUpRequest,
+} from '../../../../types/infraOrchestration.js';
+import { resolveInfraEnvironment } from '../../domain/resolveInfraEnvironment.js';
+import { appendInfraFailure } from '../../utils/appendInfraFailure.js';
+import { createInfraExecutionContext } from '../../utils/createInfraExecutionContext.js';
+import { createInfraLedger } from '../../utils/createInfraLedger.js';
+import { mergeInfraOutputs } from '../../utils/mergeInfraOutputs.js';
+import { collectInfraWorkloadsAsync } from './collectInfraWorkloadsAsync.js';
+import { resolveInfraAdaptersAsync } from './resolveInfraAdaptersAsync.js';
+import { validateInfraAdaptersAsync } from './validateInfraAdaptersAsync.js';
+
+/*** Validate and reconcile compute, contributed workloads, runtime and services in dependency order. */
+export async function upInfraEnvironmentAsync(
+  request: InfraUpRequest,
+  dependencies: InfraOrchestrationDependencies,
+): Promise<InfraUpOperationResult> {
+  const environment = resolveInfraEnvironment({
+    manifest: request.manifest,
+    environment: request.environment,
+    operation: 'up',
+  });
+  if (!environment.ok) return environment;
+  const diagnostics: InfraDiagnostic[] = [...environment.diagnostics];
+  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.ensureAsync(
+    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,
+    workloads: [...(environment.value.desired.workloads ?? []), ...workloads.value],
+    availableOutputs: mergeInfraOutputs(request.previous?.outputs ?? [], compute.value.outputs),
+  };
+  const runtimeValidation = await adapters.value.runtime.validateAsync(context, runtimeDesired);
+  if (!runtimeValidation.ok) return appendInfraFailure(diagnostics, runtimeValidation);
+  diagnostics.push(...runtimeValidation.diagnostics);
+  const runtime = await adapters.value.runtime.ensureAsync(context, runtimeDesired);
+  if (!runtime.ok) return appendInfraFailure(diagnostics, runtime);
+  diagnostics.push(...runtime.diagnostics);
+  const services = await reconcileServicesAsync(context, adapters.value.services, [
+    ...compute.value.outputs,
+    ...runtime.value.outputs,
+  ]);
+  if (!services.ok) return appendInfraFailure(diagnostics, services);
+  diagnostics.push(...services.diagnostics);
+  const resources = [
+    ...compute.value.resources,
+    ...runtime.value.resources,
+    ...services.value.resources,
+  ];
+  const outputs = mergeInfraOutputs(
+    compute.value.outputs,
+    runtime.value.outputs,
+    services.value.outputs,
+  );
+  const ledger = createInfraLedger({
+    projectId: request.projectId,
+    environment: environment.value.id,
+    targets: compute.value.targets,
+    resources,
+    outputs,
+    previous: request.previous,
+  });
+  return {
+    ok: true,
+    value: {
+      environment: environment.value.id,
+      targets: compute.value.targets,
+      resources,
+      outputs,
+      ledger,
+    },
+    diagnostics,
+  };
+}
+
+/*** Reconcile service-owned external state after its runtime workloads expose outputs. */
+async function reconcileServicesAsync(
+  context: InfraExecutionContext,
+  services: readonly InfraServiceAdapter[],
+  runtimeOutputs: readonly InfraOutput[],
+): Promise<
+  InfraResult<{
+    readonly resources: readonly InfraOwnedResource[];
+    readonly outputs: readonly InfraOutput[];
+  }>
+> {
+  const resources: InfraOwnedResource[] = [];
+  const outputs: InfraOutput[] = [];
+  const diagnostics: InfraDiagnostic[] = [];
+  for (const service of services) {
+    const result = await service.reconcileAsync(context, runtimeOutputs);
+    if (!result.ok) return appendInfraFailure(diagnostics, result);
+    resources.push(...result.value.resources);
+    outputs.push(...result.value.outputs);
+    diagnostics.push(...result.diagnostics);
+  }
+  return { ok: true, value: { resources, outputs }, diagnostics };
+}

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

@@ -0,0 +1,25 @@
+import type {
+  InfraDiagnostic,
+  InfraExecutionContext,
+  InfraResult,
+} from '@ankhorage/contracts/infra';
+
+import type { ResolvedInfraAdapters } from '../../../../types/infraOrchestration.js';
+import { appendInfraFailure } from '../../utils/appendInfraFailure.js';
+
+/*** Validate compute and service configuration before any mutating adapter call. */
+export async function validateInfraAdaptersAsync(
+  context: InfraExecutionContext,
+  adapters: ResolvedInfraAdapters,
+): Promise<InfraResult<null>> {
+  const diagnostics: InfraDiagnostic[] = [];
+  const compute = await adapters.compute.validateAsync(context, context.desired.deployment.compute);
+  if (!compute.ok) return compute;
+  diagnostics.push(...compute.diagnostics);
+  for (const service of adapters.services) {
+    const validation = await service.validateAsync(context);
+    if (!validation.ok) return appendInfraFailure(diagnostics, validation);
+    diagnostics.push(...validation.diagnostics);
+  }
+  return { ok: true, value: null, diagnostics };
+}

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

@@ -0,0 +1,21 @@
+import type {
+  InfraOperationRequest,
+  InfraOrchestrationDependencies,
+  InfraValidateOperationResult,
+} from '../../../../types/infraOrchestration.js';
+import { prepareInfraOperationAsync } from './prepareInfraOperationAsync.js';
+
+/*** Validate one environment and every selected adapter without mutating infrastructure. */
+export async function validateInfraEnvironmentAsync(
+  request: InfraOperationRequest,
+  dependencies: InfraOrchestrationDependencies,
+): Promise<InfraValidateOperationResult> {
+  const prepared = await prepareInfraOperationAsync(request, 'validate', dependencies);
+  return prepared.ok
+    ? {
+        ok: true,
+        value: { environment: prepared.value.environment.id },
+        diagnostics: prepared.diagnostics,
+      }
+    : prepared;
+}

package/src/features/environment-lifecycle/composition/createInfraCommandServices.ts

@@ -0,0 +1,47 @@
+import type { InfraCommandServices } from '../../../types/infraCli.js';
+import { createEnvironmentInfraCredentialPort } from '../adapters/outbound/createEnvironmentInfraCredentialPort.js';
+import { createEnvironmentInfraSecretPort } from '../adapters/outbound/createEnvironmentInfraSecretPort.js';
+import { createNodeInfraAdapterPackageResolver } from '../adapters/outbound/createNodeInfraAdapterPackageResolver.js';
+import { readStoredInfraStateAsync } from '../adapters/outbound/readStoredInfraStateAsync.js';
+import { removeStoredInfraStateAsync } from '../adapters/outbound/removeStoredInfraStateAsync.js';
+import { resolveInfraProjectAsync } from '../adapters/outbound/resolveInfraProjectAsync.js';
+import { writeInfraGeneratedArtifactsAsync } from '../adapters/outbound/writeInfraGeneratedArtifactsAsync.js';
+import { writeStoredInfraStateAsync } from '../adapters/outbound/writeStoredInfraStateAsync.js';
+import { destroyInfraEnvironmentAsync } from '../application/use-cases/destroyInfraEnvironmentAsync.js';
+import { downInfraEnvironmentAsync } from '../application/use-cases/downInfraEnvironmentAsync.js';
+import { generateInfraEnvironmentAsync } from '../application/use-cases/generateInfraEnvironmentAsync.js';
+import { getInfraEnvironmentOutputs } from '../application/use-cases/getInfraEnvironmentOutputs.js';
+import { planInfraEnvironmentAsync } from '../application/use-cases/planInfraEnvironmentAsync.js';
+import { statusInfraEnvironmentAsync } from '../application/use-cases/statusInfraEnvironmentAsync.js';
+import { upInfraEnvironmentAsync } from '../application/use-cases/upInfraEnvironmentAsync.js';
+import { validateInfraEnvironmentAsync } from '../application/use-cases/validateInfraEnvironmentAsync.js';
+
+/*** Compose command use cases with filesystem, environment-value and package-resolver adapters. */
+export function createInfraCommandServices(
+  overrides: Partial<InfraCommandServices> = {},
+): InfraCommandServices {
+  return {
+    resolveProject: overrides.resolveProject ?? resolveInfraProjectAsync,
+    readState: overrides.readState ?? readStoredInfraStateAsync,
+    writeState: overrides.writeState ?? writeStoredInfraStateAsync,
+    removeState: overrides.removeState ?? removeStoredInfraStateAsync,
+    writeArtifacts: overrides.writeArtifacts ?? writeInfraGeneratedArtifactsAsync,
+    operations: overrides.operations ?? {
+      validate: validateInfraEnvironmentAsync,
+      plan: planInfraEnvironmentAsync,
+      generate: generateInfraEnvironmentAsync,
+      up: upInfraEnvironmentAsync,
+      status: statusInfraEnvironmentAsync,
+      outputs: getInfraEnvironmentOutputs,
+      down: downInfraEnvironmentAsync,
+      destroy: destroyInfraEnvironmentAsync,
+    },
+    createDependencies:
+      overrides.createDependencies ??
+      ((context) => ({
+        adapterResolver: createNodeInfraAdapterPackageResolver(),
+        credentials: createEnvironmentInfraCredentialPort(context.env),
+        secrets: createEnvironmentInfraSecretPort(context.env),
+      })),
+  };
+}

package/src/features/environment-lifecycle/composition/createProjectInfraLifecycle.ts

@@ -0,0 +1,157 @@
+import type { InfraEnvironmentSpec, InfraManifest } from '@ankhorage/contracts/infra';
+
+import { INFRA_PACKAGE_VERSION } from '../../../constants.js';
+import type { InfraOperationRequest, InfraStoredState } from '../../../types/infraOrchestration.js';
+import type {
+  CreateProjectInfraLifecycleOptions,
+  ProjectInfraLifecycle,
+  ProjectInfraOperationRequest,
+} from '../../../types/infraProject.js';
+import { createInfraCommandServices } from './createInfraCommandServices.js';
+
+/*** Create the typed project-facing Infra lifecycle backed by canonical use cases and ownership state. */
+export function createProjectInfraLifecycle(
+  options: CreateProjectInfraLifecycleOptions = {},
+): ProjectInfraLifecycle {
+  const services = createInfraCommandServices(options.services);
+  return {
+    async validateAsync(request) {
+      const prepared = await prepareProjectOperationAsync(request, services);
+      return services.operations.validate(prepared.operation, prepared.dependencies);
+    },
+    async planAsync(request) {
+      const prepared = await prepareProjectOperationAsync(request, services);
+      return services.operations.plan(prepared.operation, prepared.dependencies);
+    },
+    async generateAsync(request) {
+      const prepared = await prepareProjectOperationAsync(request, services);
+      const result = await services.operations.generate(prepared.operation, prepared.dependencies);
+      if (!result.ok) return result;
+      await services.writeArtifacts(
+        request.projectPath,
+        result.value.artifacts,
+        prepared.state?.ledger,
+      );
+      await services.writeState(request.projectPath, {
+        schemaVersion: 1,
+        desired: prepared.desired,
+        ledger: result.value.ledger,
+      });
+      return result;
+    },
+    async upAsync(request) {
+      const prepared = await prepareProjectOperationAsync(request, services);
+      const result = await services.operations.up(prepared.operation, prepared.dependencies);
+      if (!result.ok) return result;
+      await services.writeState(request.projectPath, {
+        schemaVersion: 1,
+        desired: prepared.desired,
+        ledger: result.value.ledger,
+      });
+      return result;
+    },
+    async statusAsync(request) {
+      const prepared = await prepareProjectOperationAsync(request, services);
+      return services.operations.status(prepared.operation, prepared.dependencies);
+    },
+    async outputsAsync(request) {
+      const prepared = await prepareProjectOperationAsync(request, services);
+      return services.operations.outputs(prepared.operation);
+    },
+    async downAsync(request) {
+      const prepared = await prepareProjectOperationAsync(request, services);
+      const result = await services.operations.down(prepared.operation, prepared.dependencies);
+      if (!result.ok) return result;
+      await services.writeState(request.projectPath, {
+        schemaVersion: 1,
+        desired: prepared.desired,
+        ledger: result.value.ledger,
+      });
+      return result;
+    },
+    async destroyAsync(request) {
+      const prepared = await prepareProjectOperationAsync(request, services, true);
+      const result = await services.operations.destroy(
+        {
+          ...prepared.operation,
+          confirmation: request.confirmation,
+          persistence: request.persistence,
+        },
+        prepared.dependencies,
+      );
+      if (!result.ok) return result;
+      await services.writeArtifacts(request.projectPath, [], prepared.state?.ledger);
+      if (result.value.ledger === null)
+        await services.removeState(request.projectPath, request.environment);
+      else {
+        await services.writeState(request.projectPath, {
+          schemaVersion: 1,
+          desired: prepared.desired,
+          ledger: result.value.ledger,
+        });
+      }
+      return result;
+    },
+  };
+}
+
+interface PreparedProjectOperation {
+  readonly operation: InfraOperationRequest;
+  readonly desired: InfraEnvironmentSpec;
+  readonly state: InfraStoredState | null;
+  readonly dependencies: ReturnType<
+    ReturnType<typeof createInfraCommandServices>['createDependencies']
+  >;
+}
+
+/*** Resolve one explicit project/environment request with its prior ownership state and dependencies. */
+async function prepareProjectOperationAsync(
+  request: ProjectInfraOperationRequest,
+  services: ReturnType<typeof createInfraCommandServices>,
+  useStoredDesired = false,
+): Promise<PreparedProjectOperation> {
+  const state = await services.readState(request.projectPath, request.environment);
+  const currentDesired = readEnvironment(request.manifest, request.environment);
+  const desired = useStoredDesired && state !== null ? state.desired : currentDesired;
+  if (desired === undefined) {
+    throw new Error(`Infra environment "${request.environment}" is not configured.`);
+  }
+  const context = {
+    cwd: request.projectPath,
+    env: request.executionEnvironment ?? process.env,
+    version: INFRA_PACKAGE_VERSION,
+    writeStdout: () => undefined,
+    writeStderr: () => undefined,
+  };
+  return {
+    state,
+    desired,
+    operation: {
+      projectId: request.projectId,
+      manifest: replaceEnvironment(request.manifest, request.environment, desired),
+      environment: request.environment,
+      ...(state === null ? {} : { previous: state.ledger, previousDesired: state.desired }),
+      ...(request.signal === undefined ? {} : { signal: request.signal }),
+    },
+    dependencies: services.createDependencies(context),
+  };
+}
+
+/*** Read one exact environment without inventing a fallback. */
+function readEnvironment(
+  manifest: InfraManifest,
+  environment: ProjectInfraOperationRequest['environment'],
+): InfraEnvironmentSpec | undefined {
+  if (environment === 'local') return manifest.environments.local;
+  if (environment === 'preview') return manifest.environments.preview;
+  return manifest.environments.production;
+}
+
+/*** Replace one selected environment while preserving all other manifest state. */
+function replaceEnvironment(
+  manifest: InfraManifest,
+  environment: ProjectInfraOperationRequest['environment'],
+  desired: InfraEnvironmentSpec,
+): InfraManifest {
+  return { ...manifest, environments: { ...manifest.environments, [environment]: desired } };
+}

package/src/features/environment-lifecycle/domain/orderInfraPlanActions.ts

@@ -0,0 +1,64 @@
+import type {
+  InfraPlanAction,
+  InfraResourceIdentity,
+  InfraResult,
+} from '@ankhorage/contracts/infra';
+
+/*** Order plan actions dependency-first and reject duplicate owners or dependency cycles. */
+export function orderInfraPlanActions(
+  actions: readonly InfraPlanAction[],
+): InfraResult<readonly InfraPlanAction[]> {
+  const byOwner = new Map(actions.map((action) => [identityKey(action.owner), action]));
+  if (byOwner.size !== actions.length) return invalidPlan('duplicate resource actions');
+  const ordered: InfraPlanAction[] = [];
+  const complete = new Set<string>();
+  const active = new Set<string>();
+  for (const action of actions) {
+    const result = visitAction(action, byOwner, ordered, complete, active);
+    if (!result.ok) return result;
+  }
+  return { ok: true, value: ordered, diagnostics: [] };
+}
+
+/*** Visit one plan node and its in-plan dependencies exactly once. */
+function visitAction(
+  action: InfraPlanAction,
+  byOwner: ReadonlyMap<string, InfraPlanAction>,
+  ordered: InfraPlanAction[],
+  complete: Set<string>,
+  active: Set<string>,
+): InfraResult<null> {
+  const key = identityKey(action.owner);
+  if (complete.has(key)) return { ok: true, value: null, diagnostics: [] };
+  if (active.has(key)) return invalidPlan('a dependency cycle');
+  active.add(key);
+  for (const dependency of action.dependsOn) {
+    const dependencyAction = byOwner.get(identityKey(dependency));
+    if (dependencyAction === undefined) continue;
+    const result = visitAction(dependencyAction, byOwner, ordered, complete, active);
+    if (!result.ok) return result;
+  }
+  active.delete(key);
+  complete.add(key);
+  ordered.push(action);
+  return { ok: true, value: null, diagnostics: [] };
+}
+
+/*** Create a collision-safe key for one provider-owned resource identity. */
+function identityKey(identity: InfraResourceIdentity): string {
+  return `${identity.projectId}\0${identity.environment}\0${identity.adapter}\0${identity.resourceId}`;
+}
+
+/*** Reject an invalid aggregated plan without exposing provider internals. */
+function invalidPlan(detail: string): InfraResult<never> {
+  return {
+    ok: false,
+    diagnostics: [
+      {
+        severity: 'error',
+        code: 'infra-plan-invalid',
+        message: `The aggregated infrastructure plan contains ${detail}.`,
+      },
+    ],
+  };
+}

package/src/features/environment-lifecycle/domain/resolveInfraEnvironment.ts

@@ -0,0 +1,62 @@
+import { APP_ENVIRONMENT_IDS, type AppEnvironmentId } from '@ankhorage/contracts/environments';
+import type { InfraResult } from '@ankhorage/contracts/infra';
+
+import type {
+  InfraEnvironmentResolutionRequest,
+  ResolvedInfraEnvironment,
+} from '../../../types/infraOrchestration.js';
+
+/*** Resolve one explicitly configured environment while keeping local as the only safe default. */
+export function resolveInfraEnvironment(
+  request: InfraEnvironmentResolutionRequest,
+): InfraResult<ResolvedInfraEnvironment> {
+  if (request.operation === 'destroy' && request.environment === undefined) {
+    return failure(
+      'infra-environment-required',
+      'Infra destroy requires an explicit --environment selection.',
+    );
+  }
+  const environment = request.environment ?? 'local';
+  if (!isAppEnvironmentId(environment)) {
+    return failure(
+      'infra-environment-invalid',
+      `Unknown Infra environment "${environment}". Expected local, preview, or production.`,
+    );
+  }
+  const desired = getEnvironment(request.manifest, environment);
+  return desired === undefined
+    ? failure(
+        'infra-environment-unconfigured',
+        `Infra environment "${environment}" is not configured.`,
+      )
+    : {
+        ok: true,
+        value: { id: environment, desired, manifest: request.manifest },
+        diagnostics: [],
+      };
+}
+
+/*** Read a closed environment key without an open object-injection boundary. */
+function getEnvironment(
+  manifest: InfraEnvironmentResolutionRequest['manifest'],
+  environment: AppEnvironmentId,
+) {
+  switch (environment) {
+    case 'local':
+      return manifest.environments.local;
+    case 'preview':
+      return manifest.environments.preview;
+    case 'production':
+      return manifest.environments.production;
+  }
+}
+
+/*** Narrow a CLI environment string through the canonical Contracts vocabulary. */
+function isAppEnvironmentId(value: string): value is AppEnvironmentId {
+  return APP_ENVIRONMENT_IDS.some((environment) => environment === value);
+}
+
+/*** Create a stable environment-resolution diagnostic. */
+function failure(code: string, message: string): InfraResult<never> {
+  return { ok: false, diagnostics: [{ severity: 'error', code, message }] };
+}

package/src/features/environment-lifecycle/utils/appendInfraFailure.ts

@@ -0,0 +1,9 @@
+import type { InfraDiagnostic, InfraResult } from '@ankhorage/contracts/infra';
+
+/*** Preserve earlier safe diagnostics when a later lifecycle stage fails. */
+export function appendInfraFailure(
+  previous: readonly InfraDiagnostic[],
+  failure: { readonly ok: false; readonly diagnostics: readonly InfraDiagnostic[] },
+): InfraResult<never> {
+  return { ok: false, diagnostics: [...previous, ...failure.diagnostics] };
+}

package/src/features/environment-lifecycle/utils/createInfraExecutionContext.ts

@@ -0,0 +1,24 @@
+import type { InfraExecutionContext } from '@ankhorage/contracts/infra';
+
+import type {
+  InfraOperationRequest,
+  InfraOrchestrationDependencies,
+  ResolvedInfraEnvironment,
+} from '../../../types/infraOrchestration.js';
+
+/*** Create one execution context without copying resolved secret values into serializable state. */
+export function createInfraExecutionContext(
+  request: InfraOperationRequest,
+  environment: ResolvedInfraEnvironment,
+  dependencies: InfraOrchestrationDependencies,
+): InfraExecutionContext {
+  return {
+    projectId: request.projectId,
+    environment: environment.id,
+    desired: environment.desired,
+    ...(request.previous === undefined ? {} : { previous: request.previous }),
+    ...(request.signal === undefined ? {} : { signal: request.signal }),
+    credentials: dependencies.credentials,
+    secrets: dependencies.secrets,
+  };
+}

package/src/features/environment-lifecycle/utils/createInfraFailure.ts

@@ -0,0 +1,6 @@
+import type { InfraResult } from '@ankhorage/contracts/infra';
+
+/*** Create one sanitized provider-neutral Infra failure. */
+export function createInfraFailure(code: string, message: string): InfraResult<never> {
+  return { ok: false, diagnostics: [{ severity: 'error', code, message }] };
+}

package/src/features/environment-lifecycle/utils/createInfraLedger.ts

@@ -0,0 +1,30 @@
+import type {
+  InfraComputeTarget,
+  InfraGeneratedArtifact,
+  InfraLedger,
+  InfraOutput,
+  InfraOwnedResource,
+} from '@ankhorage/contracts/infra';
+
+/*** Create deterministic serializable lifecycle state without resolved credential or secret values. */
+export function createInfraLedger(input: {
+  readonly projectId: string;
+  readonly environment: InfraLedger['environment'];
+  readonly targets: readonly InfraComputeTarget[];
+  readonly resources: readonly InfraOwnedResource[];
+  readonly outputs: readonly InfraOutput[];
+  readonly artifacts?: readonly InfraGeneratedArtifact[];
+  readonly previous?: InfraLedger;
+}): InfraLedger {
+  const artifacts =
+    input.artifacts?.map(({ owner, path }) => ({ owner, path })) ?? input.previous?.artifacts ?? [];
+  return {
+    schemaVersion: 1,
+    projectId: input.projectId,
+    environment: input.environment,
+    targets: input.targets,
+    resources: input.resources,
+    outputs: input.outputs,
+    artifacts,
+  };
+}

package/src/features/environment-lifecycle/utils/infraIdentityKey.ts

@@ -0,0 +1,6 @@
+import type { InfraResourceIdentity } from '@ankhorage/contracts/infra';
+
+/*** Create a stable collision-safe key for an Infra-owned resource. */
+export function infraIdentityKey(identity: InfraResourceIdentity): string {
+  return `${identity.projectId}\0${identity.environment}\0${identity.adapter}\0${identity.resourceId}`;
+}