@ankhorage/contracts 14.0.0 → 15.0.0

package/src/media.ts

@@ -1,10 +1,13 @@
+import { isRecord } from '@ankhorage/utility/object';
+import { isNonEmptyString } from '@ankhorage/utility/string';
+
 export const MEDIA_ASSET_KINDS = ['image', 'audio', 'video', 'font', 'file'] as const;
 
 export type MediaAssetKind = (typeof MEDIA_ASSET_KINDS)[number];
 
 export interface MediaStorageSource {
   readonly kind: 'storage';
-  /** Optional logical storage connection identifier for future multi-storage apps. */
+  /*** Optional logical storage connection identifier for future multi-storage apps. */
   readonly storageId?: string;
   readonly bucket: string;
   readonly path: string;
@@ -12,13 +15,13 @@ export interface MediaStorageSource {
 
 export interface MediaUrlSource {
   readonly kind: 'url';
-  /** Stable remote URL. Transient/local URL schemes are not canonical media sources. */
+  /*** Stable remote URL. Transient/local URL schemes are not canonical media sources. */
   readonly url: string;
 }
 
 export interface MediaBundledSource {
   readonly kind: 'bundled';
-  /** App-relative bundled asset path resolved by the generated/runtime host. */
+  /*** App-relative bundled asset path resolved by the generated/runtime host. */
   readonly path: string;
 }
 
@@ -33,7 +36,7 @@ export interface MediaAssetMetadata {
   readonly durationMs?: number;
 }
 
-/** Canonical Studio-managed authoring media entry. */
+/*** Canonical Studio-managed authoring media entry. */
 export interface MediaAsset {
   readonly id: string;
   readonly name: string;
@@ -45,24 +48,22 @@ export interface MediaAsset {
 
 export type MediaAssetRegistry = Readonly<Record<string, MediaAsset>>;
 
-/** App-authoring media pool. Runtime/user-generated uploads do not belong here. */
+/*** App-authoring media pool. Runtime/user-generated uploads do not belong here. */
 export interface MediaManifest {
   readonly assets: MediaAssetRegistry;
 }
 
-/** Stable component/property reference to one entry in `AppManifest.media.assets`. */
+/*** Stable component/property reference to one entry in `AppManifest.media.assets`. */
 export interface MediaAssetReference {
   readonly mediaId: string;
 }
 
+/*** Validate an authored media reference with exactly one enumerable key and a non-empty media ID. */
 export function isMediaAssetReference(value: unknown): value is MediaAssetReference {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    !Array.isArray(value) &&
+    isRecord(value) &&
     Object.keys(value).length === 1 &&
     'mediaId' in value &&
-    typeof value.mediaId === 'string' &&
-    value.mediaId.trim().length > 0
+    isNonEmptyString(value.mediaId)
   );
 }

package/src/profile-contract.test.ts

@@ -4,7 +4,7 @@ import {
   AUTH_PROFILE_CREATE_STRATEGIES,
   AUTH_PROFILE_PRIMARY_KEY_STRATEGIES,
   AUTH_PROFILE_UPDATE_STRATEGIES,
-  type AuthSpec,
+  type InfraAuthSpec,
 } from './index';
 
 describe('profile contract', () => {
@@ -15,10 +15,9 @@ describe('profile contract', () => {
   });
 
   it('serializes profile settings on an auth spec', () => {
-    const auth: AuthSpec = {
+    const auth: InfraAuthSpec = {
       scope: 'global',
       provider: 'supabase',
-      authorization: { kind: 'RBAC', engine: 'native' },
       profile: {
         fields: ['email', 'displayName', 'avatarUrl'],
         table: 'profiles',

package/src/secrets.test.ts

@@ -1,15 +1,13 @@
-import './secretManifest';
-
 import { describe, expect, test } from 'bun:test';
 
 import type { AuthOAuthProviderConfig } from './auth';
+import type { InfraManifest } from './infra';
 import {
   findForbiddenInlineSecretFields,
   normalizeSecretRef,
   normalizeSecretScope,
   validateSecretPayload,
 } from './secrets';
-import type { InfraManifest } from './types';
 
 describe('secret-store contracts', () => {
   test('normalizes logical secret references', () => {
@@ -70,19 +68,27 @@ describe('secret-store contracts', () => {
 
     const infra: InfraManifest = {
       modules: [],
-      secretStore: { provider: 'supabase-vault' },
-      auth: {
-        scope: 'global',
-        provider: 'supabase',
-        oauth: {
-          enabled: true,
-          callbackRoute: '/auth/callback',
-          providers: [provider],
+      environments: {
+        local: {
+          deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
+          database: { provider: 'supabase' },
+          secretStore: { provider: 'supabase-vault' },
+          auth: {
+            scope: 'global',
+            provider: 'supabase',
+            oauth: {
+              enabled: true,
+              callbackRoute: '/auth/callback',
+              providers: [provider],
+            },
+          },
         },
       },
     };
 
-    expect(infra.secretStore?.provider).toBe('supabase-vault');
-    expect(infra.auth?.oauth?.providers[0]?.credentialsRef).toBe('auth/oauth/google');
+    expect(infra.environments.local.secretStore?.provider).toBe('supabase-vault');
+    expect(infra.environments.local.auth?.oauth?.providers[0]?.credentialsRef).toBe(
+      'auth/oauth/google',
+    );
   });
 });

package/src/state.ts

@@ -1,3 +1,9 @@
+/** Legend currently implements in-memory state only; unsupported persistence cannot be selected. */
+export interface AppStateSpec {
+  readonly provider: 'legend';
+  readonly persistence?: false;
+}
+
 export type StatePrimitive = string | number | boolean | null;
 
 export type StateValue =

package/src/types/appManifest.ts

@@ -0,0 +1,5 @@
+import type { AppManifest } from '../types';
+
+export type AppManifestParseResult =
+  | { readonly ok: true; readonly manifest: AppManifest }
+  | { readonly ok: false; readonly message: string };

package/src/types/infraAdapters.ts

@@ -0,0 +1,148 @@
+import type { AppEnvironmentId } from '../environments';
+import type { INFRA_ADAPTER_CATALOG } from '../infra/constants';
+import type {
+  InfraDestroyRequest,
+  InfraGeneratedArtifact,
+  InfraLedger,
+  InfraOutput,
+  InfraOwnedResource,
+  InfraPlanAction,
+  InfraResourceStatus,
+  InfraResult,
+} from './infraLifecycle';
+import type {
+  InfraAdapterId,
+  InfraComputeProviderId,
+  InfraComputeSelection,
+  InfraEnvironmentSpec,
+  InfraRuntimeProviderId,
+  InfraRuntimeSelection,
+} from './infraManifest';
+import type { InfraControlPlaneCredentialRef, InfraSecretReference } from './infraSecrets';
+import type { InfraWorkloadSpec } from './infraWorkload';
+
+/** Package exports must match this exact catalog entry; optional operations are advertised explicitly. */
+export type InfraAdapterDescriptor<P extends InfraAdapterId = InfraAdapterId> = {
+  [K in P]: (typeof INFRA_ADAPTER_CATALOG)[K] & {
+    readonly operations?: readonly ('suspend' | 'resume' | 'generate' | 'diagnostics')[];
+  };
+}[P];
+
+export type InfraComputeTarget = {
+  readonly id: string;
+  readonly os: 'linux' | 'darwin' | 'windows';
+  readonly architecture: 'amd64' | 'arm64';
+} & (
+  | { readonly kind: 'local-host' }
+  | {
+      readonly kind: 'ssh-host';
+      readonly host: string;
+      readonly port: number;
+      readonly user: string;
+      readonly credential: InfraControlPlaneCredentialRef;
+      /** Expected host key supplied by the compute owner; runtimes must verify host authenticity. */
+      readonly hostKeyFingerprint: string;
+    }
+);
+
+/** Trusted execution-only ports. Implementations must not serialize resolved credential values. */
+export interface InfraExecutionContext {
+  readonly projectId: string;
+  readonly environment: AppEnvironmentId;
+  readonly desired: InfraEnvironmentSpec;
+  readonly previous?: InfraLedger;
+  readonly signal?: AbortSignal;
+  readonly credentials: {
+    resolveAsync(
+      reference: InfraControlPlaneCredentialRef,
+    ): Promise<InfraResult<Readonly<Record<string, string>>>>;
+  };
+  readonly secrets: {
+    resolveAsync(reference: InfraSecretReference): Promise<InfraResult<string>>;
+  };
+}
+
+export interface InfraReconcileResult {
+  readonly resources: readonly InfraOwnedResource[];
+  readonly outputs: readonly InfraOutput[];
+}
+
+export interface InfraComputeAdapter<P extends InfraComputeProviderId = InfraComputeProviderId> {
+  readonly descriptor: InfraAdapterDescriptor<P>;
+  /** Read-only prerequisites, config and control-plane credential validation. */
+  validateAsync(
+    context: InfraExecutionContext,
+    selection: InfraComputeSelection<P>,
+  ): Promise<InfraResult<null>>;
+  planAsync(
+    context: InfraExecutionContext,
+    selection: InfraComputeSelection<P>,
+  ): Promise<InfraResult<readonly InfraPlanAction[]>>;
+  ensureAsync(
+    context: InfraExecutionContext,
+    selection: InfraComputeSelection<P>,
+  ): Promise<
+    InfraResult<InfraReconcileResult & { readonly targets: readonly InfraComputeTarget[] }>
+  >;
+  statusAsync(context: InfraExecutionContext): Promise<InfraResult<readonly InfraResourceStatus[]>>;
+  destroyAsync(
+    context: InfraExecutionContext,
+    request: InfraDestroyRequest,
+  ): Promise<InfraResult<InfraReconcileResult>>;
+}
+
+export interface InfraRuntimeDesiredState<
+  P extends InfraRuntimeProviderId = InfraRuntimeProviderId,
+> {
+  readonly selection: InfraRuntimeSelection<P>;
+  readonly targets: readonly InfraComputeTarget[];
+  readonly workloads: readonly InfraWorkloadSpec[];
+}
+
+export interface InfraRuntimeAdapter<P extends InfraRuntimeProviderId = InfraRuntimeProviderId> {
+  readonly descriptor: InfraAdapterDescriptor<P>;
+  /** Read-only prerequisites and desired-state validation; no cluster creation. */
+  validateAsync(
+    context: InfraExecutionContext,
+    desired: InfraRuntimeDesiredState<P>,
+  ): Promise<InfraResult<null>>;
+  planAsync(
+    context: InfraExecutionContext,
+    desired: InfraRuntimeDesiredState<P>,
+  ): Promise<InfraResult<readonly InfraPlanAction[]>>;
+  ensureAsync(
+    context: InfraExecutionContext,
+    desired: InfraRuntimeDesiredState<P>,
+  ): Promise<InfraResult<InfraReconcileResult>>;
+  statusAsync(context: InfraExecutionContext): Promise<InfraResult<readonly InfraResourceStatus[]>>;
+  suspendAsync(context: InfraExecutionContext): Promise<InfraResult<InfraReconcileResult>>;
+  destroyAsync(
+    context: InfraExecutionContext,
+    request: InfraDestroyRequest,
+  ): Promise<InfraResult<InfraReconcileResult>>;
+  generateAsync?(
+    context: InfraExecutionContext,
+    desired: InfraRuntimeDesiredState<P>,
+  ): Promise<InfraResult<readonly InfraGeneratedArtifact[]>>;
+}
+
+/** A service can own several capabilities but contributes one deduplicated platform instance. */
+export interface InfraServiceAdapter {
+  readonly descriptor: InfraAdapterDescriptor<'supabase' | 'cerbos' | 'r2' | 'supabase-vault'>;
+  /** Read-only service config, bootstrap credentials and dependency validation. */
+  validateAsync(context: InfraExecutionContext): Promise<InfraResult<null>>;
+  planAsync(context: InfraExecutionContext): Promise<InfraResult<readonly InfraPlanAction[]>>;
+  desiredWorkloadsAsync(
+    context: InfraExecutionContext,
+  ): Promise<InfraResult<readonly InfraWorkloadSpec[]>>;
+  reconcileAsync(
+    context: InfraExecutionContext,
+    runtimeOutputs: readonly InfraOutput[],
+  ): Promise<InfraResult<InfraReconcileResult>>;
+  statusAsync(context: InfraExecutionContext): Promise<InfraResult<readonly InfraResourceStatus[]>>;
+  destroyAsync(
+    context: InfraExecutionContext,
+    request: InfraDestroyRequest,
+  ): Promise<InfraResult<InfraReconcileResult>>;
+  suspendAsync?(context: InfraExecutionContext): Promise<InfraResult<InfraReconcileResult>>;
+}

package/src/types/infraLifecycle.ts

@@ -0,0 +1,105 @@
+import type { AppEnvironmentId } from '../environments';
+import type { InfraAdapterId } from './infraManifest';
+import type { InfraSecretReference } from './infraSecrets';
+
+/** Identity must be verified before mutation; unowned resources must never be pruned. */
+export interface InfraResourceIdentity {
+  readonly projectId: string;
+  readonly environment: AppEnvironmentId;
+  readonly adapter: InfraAdapterId;
+  readonly resourceId: string;
+}
+
+export interface InfraOwnedResource {
+  readonly identity: InfraResourceIdentity;
+  readonly externalId?: string;
+  readonly persistent: boolean;
+  readonly retention: 'retain' | 'delete-on-destroy';
+  readonly dependsOn: readonly InfraResourceIdentity[];
+}
+
+export interface InfraDiagnostic {
+  readonly severity: 'info' | 'warning' | 'error';
+  readonly code: string;
+  /** Safe human-readable detail. Tokens and privileged values must be redacted by the producer. */
+  readonly message: string;
+  readonly path?: readonly (string | number)[];
+  readonly owner?: InfraResourceIdentity;
+}
+
+export type InfraResult<T> =
+  | { readonly ok: true; readonly value: T; readonly diagnostics: readonly InfraDiagnostic[] }
+  | { readonly ok: false; readonly diagnostics: readonly InfraDiagnostic[] };
+
+export interface InfraPlanAction {
+  readonly owner: InfraResourceIdentity;
+  readonly operation: 'create' | 'update' | 'delete' | 'retain' | 'noop';
+  readonly impact: 'none' | 'interrupts-service' | 'deletes-data';
+  readonly detail: string;
+  readonly dependsOn: readonly InfraResourceIdentity[];
+}
+
+export interface InfraPlan {
+  readonly projectId: string;
+  readonly environment: AppEnvironmentId;
+  /** Ordered dependency-first; teardown consumers reverse dependency order. */
+  readonly actions: readonly InfraPlanAction[];
+}
+
+export interface InfraResourceStatus {
+  readonly owner: InfraResourceIdentity;
+  readonly state:
+    'absent' | 'pending' | 'ready' | 'degraded' | 'stopped' | 'retained' | 'failed' | 'unknown';
+  readonly detail?: string;
+  readonly diagnostics?: readonly InfraDiagnostic[];
+}
+
+export interface InfraStatus {
+  readonly projectId: string;
+  readonly environment: AppEnvironmentId;
+  readonly state: InfraResourceStatus['state'];
+  readonly resources: readonly InfraResourceStatus[];
+}
+
+/** A privileged output has a reference, never a value field or environment export name. */
+export type InfraOutput = { readonly owner: InfraResourceIdentity; readonly name: string } & (
+  | {
+      readonly visibility: 'public';
+      readonly value: string | number | boolean;
+      readonly environmentVariable?: string;
+      readonly reference?: never;
+    }
+  | {
+      readonly visibility: 'secret';
+      readonly reference: InfraSecretReference;
+      readonly value?: never;
+      readonly environmentVariable?: never;
+    }
+);
+
+export interface InfraGeneratedArtifact {
+  readonly owner: InfraResourceIdentity;
+  /** Project-relative file path validated by the writer before touching the filesystem. */
+  readonly path: string;
+  readonly content: string;
+  readonly executable?: boolean;
+}
+
+export interface InfraLedger {
+  readonly schemaVersion: 1;
+  readonly projectId: string;
+  readonly environment: AppEnvironmentId;
+  readonly resources: readonly InfraOwnedResource[];
+  readonly artifacts: readonly { readonly owner: InfraResourceIdentity; readonly path: string }[];
+}
+
+/** No default environment or confirmation is possible for destruction. */
+export interface InfraDestroyRequest {
+  readonly projectId: string;
+  readonly environment: AppEnvironmentId;
+  readonly confirmation: { readonly projectId: string; readonly environment: AppEnvironmentId };
+  /** Data deletion is a separate, explicit resource-scoped authorization in every environment. */
+  readonly persistence:
+    | { readonly policy: 'retain' }
+    | { readonly policy: 'delete'; readonly confirmedResources: readonly InfraResourceIdentity[] };
+}

package/src/types/infraManifest.ts

@@ -0,0 +1,130 @@
+import type { AuthFlowConfig, AuthOAuthConfig } from '../auth';
+import type { ApiDefinitionList } from '../data';
+import type { AppEnvironmentId } from '../environments';
+import type { INFRA_ADAPTER_CATALOG, INFRA_RUNTIME_COMPATIBILITY } from '../infra/constants';
+import type { AuthProfileSpec, AuthScope, AuthSignInSpec, AuthSignUpSpec } from '../types';
+import type { InfraControlPlaneCredentialRef } from './infraSecrets';
+import type { InfraWorkloadSpec } from './infraWorkload';
+
+export type InfraAdapterId = keyof typeof INFRA_ADAPTER_CATALOG;
+export type InfraCapability =
+  (typeof INFRA_ADAPTER_CATALOG)[InfraAdapterId]['capabilities'][number];
+export type InfraProviderFor<C extends InfraCapability> = {
+  [P in InfraAdapterId]: C extends (typeof INFRA_ADAPTER_CATALOG)[P]['capabilities'][number]
+    ? P
+    : never;
+}[InfraAdapterId];
+export type InfraComputeProviderId = InfraProviderFor<'compute'>;
+export type InfraRuntimeProviderId = keyof typeof INFRA_RUNTIME_COMPATIBILITY;
+
+/** Non-secret provider configuration; credentials are resolved only at the execution boundary. */
+export interface InfraComputeConfigMap {
+  readonly local: { readonly workingDirectory?: string };
+  readonly hetzner: {
+    readonly location: string;
+    readonly serverType?: string;
+    readonly image?: string;
+    readonly credentials?: InfraControlPlaneCredentialRef;
+  };
+}
+
+export interface InfraRuntimeConfigMap {
+  readonly minikube: {
+    readonly profile?: string;
+    readonly driver?: 'docker' | 'podman';
+    readonly cpus?: number;
+    readonly memoryMiB?: number;
+  };
+  readonly k3s: {
+    readonly version?: string;
+    readonly topology?: { readonly servers: number; readonly agents: number };
+  };
+  readonly 'docker-compose': { readonly projectName?: string };
+}
+
+export type InfraComputeSelection<P extends InfraComputeProviderId = InfraComputeProviderId> = {
+  [K in P]: { readonly provider: K } & InfraComputeConfigMap[K];
+}[P];
+export type InfraRuntimeSelection<P extends InfraRuntimeProviderId = InfraRuntimeProviderId> = {
+  [K in P]: { readonly provider: K } & InfraRuntimeConfigMap[K];
+}[P];
+
+/** A discriminated union derived from the runtime catalog, never a Cartesian product. */
+export type InfraDeploymentSpec = {
+  [R in InfraRuntimeProviderId]: {
+    readonly compute: InfraComputeSelection<(typeof INFRA_RUNTIME_COMPATIBILITY)[R][number]>;
+    readonly runtime: InfraRuntimeSelection<R>;
+  };
+}[InfraRuntimeProviderId];
+
+export interface InfraDatabaseConfigMap {
+  readonly supabase: { readonly tier?: 'dev' | 'prod' };
+}
+export interface InfraObjectStorageConfigMap {
+  readonly supabase: { readonly buckets?: readonly string[] };
+  readonly r2: {
+    readonly buckets?: readonly string[];
+    readonly accountId?: string;
+    readonly credentials?: InfraControlPlaneCredentialRef;
+  };
+}
+export interface InfraAuthConfigMap {
+  readonly supabase: {
+    readonly scope?: AuthScope;
+    readonly flow?: AuthFlowConfig;
+    readonly signIn?: AuthSignInSpec;
+    readonly signUp?: AuthSignUpSpec;
+    readonly oauth?: AuthOAuthConfig;
+    readonly profile?: AuthProfileSpec;
+  };
+}
+export interface InfraAuthzConfigMap {
+  readonly cerbos: { readonly kind: 'RBAC' | 'ABAC' };
+}
+export interface InfraSecretStoreConfigMap {
+  readonly 'supabase-vault': { readonly schema?: string };
+}
+
+export type InfraDatabaseSpec = {
+  [P in InfraProviderFor<'database'>]: { readonly provider: P } & InfraDatabaseConfigMap[P];
+}[InfraProviderFor<'database'>];
+export type InfraObjectStorageSpec = {
+  [P in InfraProviderFor<'objectStorage'>]: {
+    readonly provider: P;
+  } & InfraObjectStorageConfigMap[P];
+}[InfraProviderFor<'objectStorage'>];
+export type InfraAuthSpec = {
+  [P in InfraProviderFor<'auth'>]: { readonly provider: P } & InfraAuthConfigMap[P];
+}[InfraProviderFor<'auth'>];
+export type InfraAuthzSpec = {
+  [P in InfraProviderFor<'authz'>]: { readonly provider: P } & InfraAuthzConfigMap[P];
+}[InfraProviderFor<'authz'>];
+export type InfraSecretStoreSpec = {
+  [P in InfraProviderFor<'secretStore'>]: { readonly provider: P } & InfraSecretStoreConfigMap[P];
+}[InfraProviderFor<'secretStore'>];
+
+export interface InfraNetworkingSpec {
+  /** Public DNS name intent, not automatic DNS/CDN vendor provisioning. */
+  readonly domain?: string;
+}
+
+export interface InfraEnvironmentSpec {
+  readonly deployment: InfraDeploymentSpec;
+  readonly database?: InfraDatabaseSpec;
+  readonly objectStorage?: InfraObjectStorageSpec;
+  readonly auth?: InfraAuthSpec;
+  readonly authz?: InfraAuthzSpec;
+  readonly secretStore?: InfraSecretStoreSpec;
+  readonly networking?: InfraNetworkingSpec;
+  readonly workloads?: readonly InfraWorkloadSpec[];
+}
+
+export interface InfraManifest {
+  readonly environments: Readonly<
+    Record<'local', InfraEnvironmentSpec> &
+      Partial<Record<Exclude<AppEnvironmentId, 'local'>, InfraEnvironmentSpec>>
+  >;
+  readonly apis?: ApiDefinitionList;
+  readonly modules: readonly string[];
+  readonly modulesConfig?: Readonly<Record<string, unknown>>;
+}

package/src/types/infraSecrets.ts

@@ -0,0 +1,16 @@
+import type { AppEnvironmentId } from '../environments';
+
+/** Bootstrap credentials cannot depend on the managed secret store being provisioned. */
+export interface InfraControlPlaneCredentialRef {
+  readonly source: 'control-plane';
+  readonly name: string;
+}
+
+/** Privileged values are never serialized into manifests, ledgers or normal outputs. */
+export interface InfraSecretReference {
+  readonly source: 'secret-store';
+  readonly projectId: string;
+  readonly environment: AppEnvironmentId;
+  readonly ref: string;
+  readonly key: string;
+}

package/src/types/infraValidation.ts

@@ -0,0 +1,2 @@
+/** Every canonical field must have a validator, including explicitly optional fields. */
+export type InfraShape<T> = { readonly [K in keyof T]-?: (value: unknown) => boolean };

package/src/types/infraWorkload.ts

@@ -0,0 +1,64 @@
+import type { InfraSecretReference } from './infraSecrets';
+
+export interface InfraWorkloadArtifact {
+  readonly kind: 'image';
+  /** Prebuilt image, optionally pinned by digest. No registry/build provider requirement. */
+  readonly image: string;
+}
+
+export type InfraWorkloadValue =
+  | { readonly kind: 'literal'; readonly value: string }
+  | { readonly kind: 'secret'; readonly reference: InfraSecretReference }
+  | { readonly kind: 'output'; readonly resourceId: string; readonly output: string };
+
+export interface InfraWorkloadPort {
+  readonly name: string;
+  readonly port: number;
+  readonly protocol?: 'tcp' | 'udp';
+}
+
+export type InfraWorkloadHealthSpec = {
+  readonly intervalSeconds?: number;
+  readonly timeoutSeconds?: number;
+  readonly failureThreshold?: number;
+} & (
+  | { readonly kind: 'http'; readonly port: number; readonly path: string }
+  | { readonly kind: 'tcp'; readonly port: number }
+  | { readonly kind: 'command'; readonly command: readonly string[] }
+);
+
+export interface InfraWorkloadResourceSpec {
+  readonly cpuMillis?: number;
+  readonly memoryMiB?: number;
+}
+
+export interface InfraWorkloadVolumeSpec {
+  readonly id: string;
+  readonly mountPath: string;
+  readonly sizeGiB: number;
+  /** Persistence survives down and is retained by default on destroy. */
+  readonly retention: 'retain' | 'delete-on-destroy';
+}
+
+/** Portable config/policy files; secret values are materialized by the runtime. */
+export interface InfraWorkloadFileSpec {
+  readonly path: string;
+  readonly content: InfraWorkloadValue;
+}
+
+export interface InfraWorkloadSpec {
+  readonly id: string;
+  readonly artifact: InfraWorkloadArtifact;
+  readonly command?: readonly string[];
+  readonly args?: readonly string[];
+  readonly ports?: readonly InfraWorkloadPort[];
+  readonly environment?: Readonly<Record<string, InfraWorkloadValue>>;
+  readonly files?: readonly InfraWorkloadFileSpec[];
+  readonly health?: InfraWorkloadHealthSpec;
+  readonly resources?: InfraWorkloadResourceSpec;
+  readonly persistence?: readonly InfraWorkloadVolumeSpec[];
+  readonly exposure?: 'internal' | 'public';
+  readonly replicas?: number;
+  /** IDs in the composed desired-state graph; the orchestrator validates missing/cyclic edges. */
+  readonly dependsOn?: readonly string[];
+}