@ankhorage/contracts 14.0.0 → 16.0.0

package/src/deploy.ts

@@ -2,17 +2,6 @@ export const APP_DEPLOY_TARGET_IDS = ['web', 'android', 'ios'] as const;
 
 export type AppDeployTargetId = (typeof APP_DEPLOY_TARGET_IDS)[number];
 
-/**
- * Logical application environments shared across platform-specific planning.
- *
- * `local` maps to local Web, iOS development, and Android debug execution.
- * Environment-specific endpoints, signing material, and credentials are owned
- * by their dedicated deployment/infra configuration rather than this identity contract.
- */
-export const APP_DEPLOY_ENVIRONMENT_IDS = ['local', 'preview', 'production'] as const;
-
-export type AppDeployEnvironmentId = (typeof APP_DEPLOY_ENVIRONMENT_IDS)[number];
-
 export interface AppDeployProviderSelection {
   readonly build?: string;
   readonly publish?: string;

package/src/environments.ts

@@ -0,0 +1,4 @@
+/** Logical application environments shared by infrastructure and application shipment. */
+export const APP_ENVIRONMENT_IDS = ['local', 'preview', 'production'] as const;
+
+export type AppEnvironmentId = (typeof APP_ENVIRONMENT_IDS)[number];

package/src/index.ts

@@ -5,12 +5,13 @@ export * from './cli';
 export * from './data';
 export * from './db';
 export * from './deploy';
+export * from './environments';
+export * from './infra';
 export * from './media';
 export * from './navigator';
 export * from './repository';
 export * from './requirements';
 export * from './runtimeCallbacks';
-export * from './secretManifest';
 export * from './secrets';
 export * from './state';
 export * from './storage';

package/src/infra/constants.ts

@@ -0,0 +1,91 @@
+/** One compatibility source for manifest types, validation, discovery and configuration UIs. */
+export const INFRA_RUNTIME_COMPATIBILITY = {
+  minikube: ['local'],
+  k3s: ['local', 'hetzner'],
+  'docker-compose': ['local', 'hetzner'],
+} as const;
+
+/** Canonical package identities. Capabilities describe ownership, not eight mandatory methods. */
+export const INFRA_ADAPTER_CATALOG = {
+  local: {
+    id: 'local',
+    package: '@ankhorage/local',
+    kind: 'compute',
+    configVersion: 1,
+    capabilities: ['compute'],
+    targets: ['local-host'],
+    dependencies: [],
+  },
+  hetzner: {
+    id: 'hetzner',
+    package: '@ankhorage/hetzner',
+    kind: 'compute',
+    configVersion: 1,
+    capabilities: ['compute'],
+    targets: ['ssh-host'],
+    dependencies: [],
+  },
+  minikube: {
+    id: 'minikube',
+    package: '@ankhorage/minikube',
+    kind: 'runtime',
+    configVersion: 1,
+    capabilities: ['runtime', 'workloads', 'networking'],
+    targets: ['local-host'],
+    dependencies: ['compute'],
+  },
+  k3s: {
+    id: 'k3s',
+    package: '@ankhorage/k3s',
+    kind: 'runtime',
+    configVersion: 1,
+    capabilities: ['runtime', 'workloads', 'networking'],
+    targets: ['local-host', 'ssh-host'],
+    dependencies: ['compute'],
+  },
+  'docker-compose': {
+    id: 'docker-compose',
+    package: '@ankhorage/docker-compose',
+    kind: 'runtime',
+    configVersion: 1,
+    capabilities: ['runtime', 'workloads', 'networking'],
+    targets: ['local-host', 'ssh-host'],
+    dependencies: ['compute'],
+  },
+  supabase: {
+    id: 'supabase',
+    package: '@ankhorage/supabase',
+    kind: 'service',
+    configVersion: 1,
+    capabilities: ['database', 'auth', 'objectStorage'],
+    targets: [],
+    dependencies: ['workloads'],
+  },
+  cerbos: {
+    id: 'cerbos',
+    package: '@ankhorage/cerbos',
+    kind: 'service',
+    configVersion: 1,
+    capabilities: ['authz'],
+    targets: [],
+    dependencies: ['workloads'],
+  },
+  r2: {
+    id: 'r2',
+    package: '@ankhorage/r2',
+    kind: 'service',
+    configVersion: 1,
+    capabilities: ['objectStorage'],
+    targets: [],
+    dependencies: [],
+  },
+  'supabase-vault': {
+    id: 'supabase-vault',
+    package: '@ankhorage/supabase-vault',
+    kind: 'service',
+    configVersion: 1,
+    capabilities: ['secretStore'],
+    targets: [],
+    dependencies: ['database'],
+  },
+} as const;

package/src/infra/infraFields.ts

@@ -0,0 +1,20 @@
+import { isStringArray } from '@ankhorage/utility/array';
+import { isNonEmptyString } from '@ankhorage/utility/string';
+
+/*** Primitive field rules for portable Infra configuration, shared by its exact-shape validators. */
+export const infraFields = {
+  optionalText: (value: unknown): boolean => value === undefined || isNonEmptyString(value),
+  strings: (value: unknown): boolean => isStringArray(value) && value.every(isNonEmptyString),
+  optionalStrings: (value: unknown): boolean =>
+    value === undefined || (isStringArray(value) && value.every(isNonEmptyString)),
+  positiveInteger: (value: unknown): boolean =>
+    typeof value === 'number' && Number.isSafeInteger(value) && value > 0,
+  nonnegativeInteger: (value: unknown): boolean =>
+    typeof value === 'number' && Number.isSafeInteger(value) && value >= 0,
+  optionalPositiveInteger: (value: unknown): boolean =>
+    value === undefined || (typeof value === 'number' && Number.isSafeInteger(value) && value > 0),
+  optionalNonnegativeInteger: (value: unknown): boolean =>
+    value === undefined || (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0),
+  port: (value: unknown): boolean =>
+    typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= 65535,
+};

package/src/infra/isInfraAdapterDescriptor.ts

@@ -0,0 +1,37 @@
+import { isRecord } from '@ankhorage/utility/object';
+
+import type { InfraAdapterDescriptor } from '../types/infraAdapters';
+import { INFRA_ADAPTER_CATALOG } from './constants';
+import { isInfraShape } from './isInfraShape';
+
+/*** Installed adapters must match the canonical identity, capabilities, targets and config version exactly. */
+export function isInfraAdapterDescriptor(value: unknown): value is InfraAdapterDescriptor {
+  if (!isRecord(value)) return false;
+  const entry = Object.values(INFRA_ADAPTER_CATALOG).find((candidate) => candidate.id === value.id);
+  if (!entry) return false;
+  return isInfraShape(value, {
+    id: (id) => id === entry.id,
+    package: (name) => name === entry.package,
+    kind: (kind) => kind === entry.kind,
+    configVersion: (version) => version === entry.configVersion,
+    capabilities: (items) => matchesCatalogList(items, entry.capabilities),
+    targets: (items) => matchesCatalogList(items, entry.targets),
+    dependencies: (items) => matchesCatalogList(items, entry.dependencies),
+    operations: (items) =>
+      items === undefined ||
+      (Array.isArray(items) &&
+        new Set(items).size === items.length &&
+        items.every((item: unknown) =>
+          ['suspend', 'resume', 'generate', 'diagnostics'].some((operation) => operation === item),
+        )),
+  });
+}
+
+/*** Canonical descriptor lists are ordered so JSON discovery and conformance are deterministic. */
+function matchesCatalogList(value: unknown, expected: readonly string[]): boolean {
+  return (
+    Array.isArray(value) &&
+    value.length === expected.length &&
+    value.every((item, index) => item === expected.at(index))
+  );
+}

package/src/infra/isInfraAuthSpec.ts

@@ -0,0 +1,98 @@
+import { isStringArray } from '@ankhorage/utility/array';
+import { isRecordOf } from '@ankhorage/utility/object';
+import { isOptionalString } from '@ankhorage/utility/string';
+
+import { isIconSpec } from '../appManifest/icon';
+import { AUTH_OAUTH_PROVIDER_IDS } from '../auth';
+import {
+  AUTH_PROFILE_CREATE_STRATEGIES,
+  AUTH_PROFILE_PRIMARY_KEY_STRATEGIES,
+  AUTH_PROFILE_UPDATE_STRATEGIES,
+  AUTH_SCOPES,
+  AUTH_SIGN_IN_IDENTIFIERS,
+  AUTH_SIGN_UP_POLICIES,
+} from '../types';
+import type { InfraAuthSpec } from '../types/infraManifest';
+import type { InfraShape } from '../types/infraValidation';
+import { isInfraShape } from './isInfraShape';
+
+/*** Preserve application auth configuration while rejecting nested authorization and unknown providers. */
+export function isInfraAuthSpec(value: unknown): value is InfraAuthSpec {
+  return isInfraShape(value, {
+    provider: (provider) => provider === 'supabase',
+    scope: (scope) => scope === undefined || AUTH_SCOPES.some((item) => item === scope),
+    flow: (flow) => flow === undefined || isAuthFlow(flow),
+    signIn: (signIn) =>
+      signIn === undefined ||
+      isInfraShape(signIn, {
+        identifiers: (ids) =>
+          Array.isArray(ids) &&
+          ids.every((id) => AUTH_SIGN_IN_IDENTIFIERS.some((item) => item === id)),
+      }),
+    signUp: (signUp) => signUp === undefined || isAuthSignUp(signUp),
+    oauth: (oauth) => oauth === undefined || isAuthOAuth(oauth),
+    profile: (profile) => profile === undefined || isAuthProfile(profile),
+  } satisfies InfraShape<InfraAuthSpec>);
+}
+
+/*** Auth routing intent stays separate from provider-runtime callbacks and Navigator topology. */
+function isAuthFlow(value: unknown): boolean {
+  return isInfraShape(value, {
+    signInRoute: (route) => typeof route === 'string',
+    postSignInRoute: (route) => typeof route === 'string',
+    signUpRoute: isOptionalString,
+    signOutRoute: isOptionalString,
+    forgotPasswordRoute: isOptionalString,
+    otpRoute: isOptionalString,
+    unauthorizedRoute: isOptionalString,
+  });
+}
+
+/*** Validate sign-up field intent using the existing application auth contract. */
+function isAuthSignUp(value: unknown): boolean {
+  return isInfraShape(value, {
+    requiredFields: isStringArray,
+    optionalFields: (fields) => fields === undefined || isStringArray(fields),
+    signUpPolicy: (policy) =>
+      policy === undefined || AUTH_SIGN_UP_POLICIES.some((item) => item === policy),
+  });
+}
+
+/*** OAuth references contain no credential payload. Custom OAuth identities remain application-owned. */
+function isAuthOAuth(value: unknown): boolean {
+  return isInfraShape(value, {
+    enabled: (enabled) => typeof enabled === 'boolean',
+    callbackRoute: (route) => typeof route === 'string',
+    providers: (providers) => Array.isArray(providers) && providers.every(isAuthOAuthProvider),
+  });
+}
+
+/*** Validate OAuth display/config metadata, preserving explicitly extensible OAuth provider IDs. */
+function isAuthOAuthProvider(value: unknown): boolean {
+  return isInfraShape(value, {
+    id: (id) =>
+      typeof id === 'string' &&
+      (AUTH_OAUTH_PROVIDER_IDS.some((item) => item === id) || id.length > 0),
+    label: isOptionalString,
+    enabled: (value) => value === undefined || typeof value === 'boolean',
+    scopes: (scopes) => scopes === undefined || isStringArray(scopes),
+    queryParams: (params) =>
+      params === undefined || isRecordOf(params, (entry) => typeof entry === 'string'),
+    icon: (icon) => icon === undefined || isIconSpec(icon),
+    credentialsRef: isOptionalString,
+  });
+}
+
+/*** Validate profile provisioning choices without inventing a new application profile model. */
+function isAuthProfile(value: unknown): boolean {
+  return isInfraShape(value, {
+    fields: isStringArray,
+    table: isOptionalString,
+    primaryKey: (key) =>
+      key === undefined || AUTH_PROFILE_PRIMARY_KEY_STRATEGIES.some((item) => item === key),
+    createStrategy: (strategy) =>
+      strategy === undefined || AUTH_PROFILE_CREATE_STRATEGIES.some((item) => item === strategy),
+    updateStrategy: (strategy) =>
+      strategy === undefined || AUTH_PROFILE_UPDATE_STRATEGIES.some((item) => item === strategy),
+  });
+}

package/src/infra/isInfraCredentialRef.ts

@@ -0,0 +1,11 @@
+import { isNonEmptyString } from '@ankhorage/utility/string';
+
+import { isInfraShape } from './isInfraShape';
+
+/*** Bootstrap credential references are explicitly separate from managed runtime secrets. */
+export function isInfraCredentialRef(value: unknown): boolean {
+  return isInfraShape(value, {
+    source: (source) => source === 'control-plane',
+    name: isNonEmptyString,
+  });
+}

package/src/infra/isInfraDeploymentSpec.ts

@@ -0,0 +1,75 @@
+import { isRecord } from '@ankhorage/utility/object';
+import { isNonEmptyString } from '@ankhorage/utility/string';
+
+import type {
+  InfraComputeSelection,
+  InfraDeploymentSpec,
+  InfraRuntimeSelection,
+} from '../types/infraManifest';
+import type { InfraShape } from '../types/infraValidation';
+import { INFRA_RUNTIME_COMPATIBILITY } from './constants';
+import { infraFields } from './infraFields';
+import { isInfraCredentialRef } from './isInfraCredentialRef';
+import { isInfraShape } from './isInfraShape';
+
+/*** Validate provider-specific config and the exact same compatibility map used by TypeScript. */
+export function isInfraDeploymentSpec(value: unknown): value is InfraDeploymentSpec {
+  if (!isInfraShape(value, { compute: isCompute, runtime: isRuntime }) || !isRecord(value))
+    return false;
+  if (!isRecord(value.compute) || !isRecord(value.runtime)) return false;
+  const compute = value.compute.provider;
+  const runtime = value.runtime.provider;
+  return Object.entries(INFRA_RUNTIME_COMPATIBILITY).some(
+    ([id, providers]) => id === runtime && providers.some((provider) => provider === compute),
+  );
+}
+
+/*** Compute configuration is closed per provider; control-plane refs cannot be managed secrets. */
+function isCompute(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  if (value.provider === 'local')
+    return isInfraShape(value, {
+      provider: (provider) => provider === 'local',
+      workingDirectory: infraFields.optionalText,
+    } satisfies InfraShape<InfraComputeSelection<'local'>>);
+  return isInfraShape(value, {
+    provider: (provider) => provider === 'hetzner',
+    location: isNonEmptyString,
+    serverType: infraFields.optionalText,
+    image: infraFields.optionalText,
+    credentials: (credentials) => credentials === undefined || isInfraCredentialRef(credentials),
+  } satisfies InfraShape<InfraComputeSelection<'hetzner'>>);
+}
+
+/*** Runtime topology expresses host roles and never couples k3s to a compute vendor. */
+function isRuntime(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  switch (value.provider) {
+    case 'minikube':
+      return isInfraShape(value, {
+        provider: (provider) => provider === 'minikube',
+        profile: infraFields.optionalText,
+        driver: (driver) => driver === undefined || driver === 'docker' || driver === 'podman',
+        cpus: infraFields.optionalPositiveInteger,
+        memoryMiB: infraFields.optionalPositiveInteger,
+      } satisfies InfraShape<InfraRuntimeSelection<'minikube'>>);
+    case 'k3s':
+      return isInfraShape(value, {
+        provider: (provider) => provider === 'k3s',
+        version: infraFields.optionalText,
+        topology: (topology) =>
+          topology === undefined ||
+          isInfraShape(topology, {
+            servers: infraFields.positiveInteger,
+            agents: infraFields.nonnegativeInteger,
+          }),
+      } satisfies InfraShape<InfraRuntimeSelection<'k3s'>>);
+    case 'docker-compose':
+      return isInfraShape(value, {
+        provider: (provider) => provider === 'docker-compose',
+        projectName: infraFields.optionalText,
+      } satisfies InfraShape<InfraRuntimeSelection<'docker-compose'>>);
+    default:
+      return false;
+  }
+}

package/src/infra/isInfraEnvironmentSpec.ts

@@ -0,0 +1,95 @@
+import { isRecord } from '@ankhorage/utility/object';
+
+import type { InfraEnvironmentSpec, InfraObjectStorageSpec } from '../types/infraManifest';
+import type { InfraShape } from '../types/infraValidation';
+import { INFRA_ADAPTER_CATALOG } from './constants';
+import { infraFields } from './infraFields';
+import { isInfraAuthSpec } from './isInfraAuthSpec';
+import { isInfraCredentialRef } from './isInfraCredentialRef';
+import { isInfraDeploymentSpec } from './isInfraDeploymentSpec';
+import { isInfraShape } from './isInfraShape';
+import { isInfraWorkloadSpec } from './isInfraWorkloadSpec';
+
+/*** Validate sibling capabilities and their required relationships within one environment. */
+export function isInfraEnvironmentSpec(value: unknown): value is InfraEnvironmentSpec {
+  return isEnvironmentShape(value) && hasServiceDependencies(value);
+}
+
+/*** Check all environment field shapes before inspecting canonical dependency metadata. */
+function isEnvironmentShape(value: unknown): value is InfraEnvironmentSpec {
+  return isInfraShape(value, {
+    deployment: isInfraDeploymentSpec,
+    database: (database) =>
+      database === undefined ||
+      isInfraShape(database, {
+        provider: (provider) => provider === 'supabase',
+        tier: (tier) => tier === undefined || tier === 'dev' || tier === 'prod',
+      }),
+    objectStorage: (storage) => storage === undefined || isObjectStorage(storage),
+    auth: (auth) => auth === undefined || isInfraAuthSpec(auth),
+    authz: (authz) =>
+      authz === undefined ||
+      isInfraShape(authz, {
+        provider: (provider) => provider === 'cerbos',
+        kind: (kind) => kind === 'ABAC' || kind === 'RBAC',
+      }),
+    secretStore: (store) =>
+      store === undefined ||
+      isInfraShape(store, {
+        provider: (provider) => provider === 'supabase-vault',
+        schema: infraFields.optionalText,
+      }),
+    networking: (networking) =>
+      networking === undefined || isInfraShape(networking, { domain: infraFields.optionalText }),
+    workloads: (workloads) => workloads === undefined || isWorkloads(workloads),
+  } satisfies InfraShape<InfraEnvironmentSpec>);
+}
+
+/*** Object storage can vary independently from database/auth; there is no implicit auto provider. */
+function isObjectStorage(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const common = {
+    provider: (provider: unknown) => provider === value.provider,
+    buckets: infraFields.optionalStrings,
+  };
+  if (value.provider === 'supabase') return isInfraShape(value, common);
+  return isInfraShape(value, {
+    ...common,
+    provider: (provider) => provider === 'r2',
+    accountId: infraFields.optionalText,
+    credentials: (credentials) => credentials === undefined || isInfraCredentialRef(credentials),
+  } satisfies InfraShape<Extract<InfraObjectStorageSpec, { readonly provider: 'r2' }>>);
+}
+
+/*** Duplicate desired workload identities cannot be reconciled safely. */
+function isWorkloads(value: unknown): boolean {
+  return (
+    Array.isArray(value) &&
+    value.every(isInfraWorkloadSpec) &&
+    new Set(value.map((workload) => workload.id)).size === value.length
+  );
+}
+
+/*** Check catalog dependencies against selected sibling capabilities and runtime capabilities. */
+function hasServiceDependencies(value: InfraEnvironmentSpec): boolean {
+  const selections = [
+    value.database,
+    value.auth,
+    value.authz,
+    value.objectStorage,
+    value.secretStore,
+  ];
+  const runtime = Object.values(INFRA_ADAPTER_CATALOG).find(
+    (entry) => entry.id === value.deployment.runtime.provider,
+  );
+  const capabilities = new Set<string>([
+    'compute',
+    ...(runtime?.capabilities ?? []),
+    ...Object.entries(value)
+      .filter(([, selection]) => selection !== undefined)
+      .map(([capability]) => capability),
+  ]);
+  return Object.values(INFRA_ADAPTER_CATALOG)
+    .filter((entry) => selections.some((selection) => selection?.provider === entry.id))
+    .every((entry) => entry.dependencies.every((dependency) => capabilities.has(dependency)));
+}

package/src/infra/isInfraManifest.ts

@@ -0,0 +1,29 @@
+import { isRecord } from '@ankhorage/utility/object';
+
+import { isApiDefinitionList } from '../appManifest/apis';
+import { APP_ENVIRONMENT_IDS } from '../environments';
+import type { InfraManifest } from '../types/infraManifest';
+import type { InfraShape } from '../types/infraValidation';
+import { infraFields } from './infraFields';
+import { isInfraEnvironmentSpec } from './isInfraEnvironmentSpec';
+import { isInfraShape } from './isInfraShape';
+
+/*** Validate standalone infrastructure without AppManifest, Deploy or provider package side effects. */
+export function isInfraManifest(value: unknown): value is InfraManifest {
+  return isInfraShape(value, {
+    environments: isEnvironments,
+    apis: (apis) => apis === undefined || isApiDefinitionList(apis),
+    modules: infraFields.strings,
+    modulesConfig: (config) => config === undefined || isRecord(config),
+  } satisfies InfraShape<InfraManifest>);
+}
+
+/*** Local is required; preview and production are optional but never inferred from arbitrary keys. */
+function isEnvironments(value: unknown): boolean {
+  if (!isRecord(value) || !isInfraEnvironmentSpec(value.local)) return false;
+  return Object.entries(value).every(
+    ([key, environment]) =>
+      APP_ENVIRONMENT_IDS.some((id) => id === key) &&
+      ((environment === undefined && key !== 'local') || isInfraEnvironmentSpec(environment)),
+  );
+}

package/src/infra/isInfraShape.ts

@@ -0,0 +1,16 @@
+import { hasOnlyKeys, isRecord } from '@ankhorage/utility/object';
+
+/*** Validate an exact Infra object shape, rejecting unknown and superseded configuration keys. */
+export function isInfraShape(
+  value: unknown,
+  fields: Readonly<Record<string, (field: unknown) => boolean>>,
+): boolean {
+  if (!isRecord(value)) return false;
+  const entries = Object.entries(fields);
+  return (
+    hasOnlyKeys(value, Object.keys(fields)) &&
+    entries.every(([key, validate]) =>
+      validate(Object.hasOwn(value, key) ? Reflect.get(value, key) : undefined),
+    )
+  );
+}

package/src/infra/isInfraWorkloadHealth.ts

@@ -0,0 +1,38 @@
+import { isRecord } from '@ankhorage/utility/object';
+
+import { infraFields } from './infraFields';
+import { isInfraShape } from './isInfraShape';
+
+/*** Validate runtime-neutral readiness probes and bounded numeric parameters. */
+export function isInfraWorkloadHealth(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const timing = {
+    intervalSeconds: infraFields.optionalPositiveInteger,
+    timeoutSeconds: infraFields.optionalPositiveInteger,
+    failureThreshold: infraFields.optionalPositiveInteger,
+  };
+  switch (value.kind) {
+    case 'http':
+      return isInfraShape(value, {
+        ...timing,
+        kind: (kind) => kind === 'http',
+        port: infraFields.port,
+        path: (path) => typeof path === 'string' && path.startsWith('/'),
+      });
+    case 'tcp':
+      return isInfraShape(value, {
+        ...timing,
+        kind: (kind) => kind === 'tcp',
+        port: infraFields.port,
+      });
+    case 'command':
+      return isInfraShape(value, {
+        ...timing,
+        kind: (kind) => kind === 'command',
+        command: (command) =>
+          Array.isArray(command) && command.length > 0 && infraFields.strings(command),
+      });
+    default:
+      return false;
+  }
+}

package/src/infra/isInfraWorkloadSpec.ts

@@ -0,0 +1,87 @@
+import { isStringArray } from '@ankhorage/utility/array';
+import { isRecord } from '@ankhorage/utility/object';
+import { isNonEmptyString } from '@ankhorage/utility/string';
+
+import type { InfraShape } from '../types/infraValidation';
+import type { InfraWorkloadSpec } from '../types/infraWorkload';
+import { infraFields } from './infraFields';
+import { isInfraShape } from './isInfraShape';
+import { isInfraWorkloadHealth } from './isInfraWorkloadHealth';
+import { isInfraWorkloadValue } from './isInfraWorkloadValue';
+
+/*** Validate the portable desired workload; runtime-specific fields and plaintext secret objects fail. */
+export function isInfraWorkloadSpec(value: unknown): value is InfraWorkloadSpec {
+  return isInfraShape(value, {
+    id: isNonEmptyString,
+    artifact: (artifact) =>
+      isInfraShape(artifact, { kind: (kind) => kind === 'image', image: isNonEmptyString }),
+    command: infraFields.optionalStrings,
+    args: (args) => args === undefined || isStringArray(args),
+    ports: (ports) =>
+      ports === undefined ||
+      (Array.isArray(ports) && ports.every(isPort) && hasUniqueField(ports, 'name')),
+    environment: (environment) =>
+      environment === undefined ||
+      (isRecord(environment) && Object.values(environment).every(isInfraWorkloadValue)),
+    files: (files) =>
+      files === undefined ||
+      (Array.isArray(files) && files.every(isFile) && hasUniqueField(files, 'path')),
+    health: (health) => health === undefined || isInfraWorkloadHealth(health),
+    resources: (resources) =>
+      resources === undefined ||
+      isInfraShape(resources, {
+        cpuMillis: infraFields.optionalPositiveInteger,
+        memoryMiB: infraFields.optionalPositiveInteger,
+      }),
+    persistence: (volumes) =>
+      volumes === undefined ||
+      (Array.isArray(volumes) &&
+        volumes.every(isVolume) &&
+        hasUniqueField(volumes, 'id') &&
+        hasUniqueField(volumes, 'mountPath')),
+    exposure: (exposure) =>
+      exposure === undefined || exposure === 'internal' || exposure === 'public',
+    replicas: infraFields.optionalNonnegativeInteger,
+    dependsOn: infraFields.optionalStrings,
+  } satisfies InfraShape<InfraWorkloadSpec>);
+}
+
+/*** Named transport ports stay independent from runtime resource types. */
+function isPort(value: unknown): boolean {
+  return isInfraShape(value, {
+    name: isNonEmptyString,
+    port: infraFields.port,
+    protocol: (protocol) => protocol === undefined || protocol === 'tcp' || protocol === 'udp',
+  });
+}
+
+/*** Portable files model policy/config materialization without host filesystem access. */
+function isFile(value: unknown): boolean {
+  return isInfraShape(value, { path: isAbsoluteWorkloadPath, content: isInfraWorkloadValue });
+}
+
+/*** Persistence has explicit ownership-local identity and a retention policy. */
+function isVolume(value: unknown): boolean {
+  return isInfraShape(value, {
+    id: isNonEmptyString,
+    mountPath: isAbsoluteWorkloadPath,
+    sizeGiB: infraFields.positiveInteger,
+    retention: (retention) => retention === 'retain' || retention === 'delete-on-destroy',
+  });
+}
+
+/*** Workload paths are absolute container paths, never relative host traversal. */
+function isAbsoluteWorkloadPath(value: unknown): boolean {
+  return (
+    typeof value === 'string' &&
+    value.startsWith('/') &&
+    value.length > 1 &&
+    !value.split('/').includes('..')
+  );
+}
+
+/*** Duplicate workload-local identities would make runtime projection ambiguous. */
+function hasUniqueField(values: readonly unknown[], field: string): boolean {
+  const ids = values.map((value) => (isRecord(value) ? Reflect.get(value, field) : undefined));
+  return new Set(ids).size === ids.length;
+}