@ankhorage/contracts 21.0.0 → 22.0.1

package/src/infra/isInfraWorkloadSpec.ts

@@ -2,6 +2,7 @@ import { isStringArray } from '@ankhorage/utility/array';
 import { isRecord } from '@ankhorage/utility/object';
 import { isNonEmptyString } from '@ankhorage/utility/string';
 
+import { isSerializableSet } from '../collections';
 import type { InfraShape } from '../types/infraValidation';
 import type { InfraWorkloadSpec } from '../types/infraWorkload';
 import { infraFields } from './infraFields';
@@ -18,15 +19,11 @@ export function isInfraWorkloadSpec(value: unknown): value is InfraWorkloadSpec
         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')),
+      ports: (ports) => ports === undefined || isPortRegistry(ports),
       environment: (environment) =>
         environment === undefined ||
         (isRecord(environment) && Object.values(environment).every(isInfraWorkloadValue)),
-      files: (files) =>
-        files === undefined ||
-        (Array.isArray(files) && files.every(isFile) && hasUniqueField(files, 'path')),
+      files: (files) => files === undefined || isFileMap(files),
       health: (health) => health === undefined || isInfraWorkloadHealth(health),
       resources: (resources) =>
         resources === undefined ||
@@ -34,16 +31,11 @@ export function isInfraWorkloadSpec(value: unknown): value is InfraWorkloadSpec
           cpuMillis: infraFields.optionalPositiveInteger,
           memoryMiB: infraFields.optionalPositiveInteger,
         }),
-      persistence: (volumes) =>
-        volumes === undefined ||
-        (Array.isArray(volumes) &&
-          volumes.every(isVolume) &&
-          hasUniqueField(volumes, 'id') &&
-          hasUniqueField(volumes, 'mountPath')),
+      persistence: (volumes) => volumes === undefined || isVolumeRegistry(volumes),
       exposure: (exposure) =>
         exposure === undefined || exposure === 'internal' || exposure === 'public',
       replicas: infraFields.optionalNonnegativeInteger,
-      dependsOn: infraFields.optionalStrings,
+      dependsOn: (dependsOn) => dependsOn === undefined || isSerializableSet(dependsOn),
     } satisfies InfraShape<InfraWorkloadSpec>)
   ) {
     return false;
@@ -51,10 +43,17 @@ export function isInfraWorkloadSpec(value: unknown): value is InfraWorkloadSpec
   return hasValidPublishedPorts(value);
 }
 
+/*** Validate named transport ports keyed by their stable authored name. */
+function isPortRegistry(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    Object.entries(value).every(([name, port]) => isNonEmptyString(name) && isPort(port))
+  );
+}
+
 /*** 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',
     publishedPort: infraFields.optionalPort,
@@ -64,7 +63,7 @@ function isPort(value: unknown): boolean {
 /*** Require fixed external listeners to belong to one public workload replica. */
 function hasValidPublishedPorts(workload: unknown): boolean {
   if (!isRecord(workload)) return false;
-  const ports = Array.isArray(workload.ports) ? workload.ports : [];
+  const ports = isRecord(workload.ports) ? Object.values(workload.ports) : [];
   const published = ports.flatMap((port) => {
     if (!isRecord(port) || typeof port.publishedPort !== 'number') return [];
     return [port.publishedPort];
@@ -78,9 +77,31 @@ function hasValidPublishedPorts(workload: unknown): boolean {
   );
 }
 
-/*** Portable files model policy/config materialization without host filesystem access. */
-function isFile(value: unknown): boolean {
-  return isInfraShape(value, { path: isAbsoluteWorkloadPath, content: isInfraWorkloadValue });
+/*** Validate portable config/policy files keyed by their absolute container path. */
+function isFileMap(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    Object.entries(value).every(
+      ([filePath, content]) => isAbsoluteWorkloadPath(filePath) && isInfraWorkloadValue(content),
+    )
+  );
+}
+
+/*** Validate persistence volumes by stable ID and keep mount paths unique within one workload. */
+function isVolumeRegistry(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const entries = Object.entries(value);
+  if (
+    !entries.every(
+      ([volumeId, volume]) => isVolume(volume) && isRecord(volume) && volume.id === volumeId,
+    )
+  ) {
+    return false;
+  }
+  const mountPaths = Object.values(value).map((volume) =>
+    isRecord(volume) ? volume.mountPath : undefined,
+  );
+  return new Set(mountPaths).size === mountPaths.length;
 }
 
 /*** Persistence has explicit ownership-local identity, optional initialization and retention policy. */
@@ -103,9 +124,3 @@ function isAbsoluteWorkloadPath(value: unknown): boolean {
     !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;
-}

package/src/infra-published-port.test.ts

@@ -5,7 +5,7 @@ import { isInfraEnvironmentSpec, isInfraWorkloadSpec } from './infra';
 const publicWorkload = {
   id: 'api',
   artifact: { kind: 'image', image: 'example/api:1' },
-  ports: [{ name: 'http', port: 8080, publishedPort: 18_080 }],
+  ports: { http: { port: 8080, publishedPort: 18_080 } },
   exposure: 'public',
 } as const;
 
@@ -17,16 +17,16 @@ describe('published workload ports', () => {
   });
 
   it.each([
-    { ...publicWorkload, ports: [{ name: 'http', port: 80, publishedPort: 0 }] },
-    { ...publicWorkload, ports: [{ name: 'http', port: 80, publishedPort: 65_536 }] },
+    { ...publicWorkload, ports: { http: { port: 80, publishedPort: 0 } } },
+    { ...publicWorkload, ports: { http: { port: 80, publishedPort: 65_536 } } },
     { ...publicWorkload, exposure: 'internal' },
     { ...publicWorkload, replicas: 2 },
     {
       ...publicWorkload,
-      ports: [
-        { name: 'http', port: 80, publishedPort: 8080 },
-        { name: 'admin', port: 81, publishedPort: 8080 },
-      ],
+      ports: {
+        http: { port: 80, publishedPort: 8080 },
+        admin: { port: 81, publishedPort: 8080 },
+      },
     },
   ])('rejects an invalid fixed external listener: %j', (workload) => {
     expect(isInfraWorkloadSpec(workload)).toBe(false);
@@ -36,7 +36,7 @@ describe('published workload ports', () => {
     expect(
       isInfraEnvironmentSpec({
         deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
-        workloads: [publicWorkload, { ...publicWorkload, id: 'admin' }],
+        workloads: { api: publicWorkload, admin: { ...publicWorkload, id: 'admin' } },
       }),
     ).toBe(false);
   });

package/src/infra-workload-persistence.test.ts

@@ -5,15 +5,15 @@ import { isInfraWorkloadSpec } from './infra';
 const workload = {
   id: 'database',
   artifact: { kind: 'image', image: 'example/database:1' },
-  persistence: [
-    {
+  persistence: {
+    config: {
       id: 'config',
       mountPath: '/etc/database-custom',
       sizeGiB: 1,
       seed: 'image',
       retention: 'retain',
     },
-  ],
+  },
 } as const;
 
 it('accepts image-seeded persistence initialization', () => {
@@ -24,7 +24,7 @@ it('rejects unsupported persistence initialization modes', () => {
   expect(
     isInfraWorkloadSpec({
       ...workload,
-      persistence: [{ ...workload.persistence[0], seed: 'empty' }],
+      persistence: { config: { ...workload.persistence.config, seed: 'empty' } },
     }),
   ).toBe(false);
 });

package/src/infra-workload.test.ts

@@ -10,6 +10,13 @@ import {
 } from './infra';
 import type { AppManifest } from './types';
 
+const defaultTheme = {
+  id: 'default',
+  name: 'Default',
+  light: { primaryColor: '#3366ff', harmony: 'analogous' },
+  dark: { primaryColor: '#6699ff', harmony: 'analogous' },
+} as const;
+
 const reference = {
   source: 'secret-store',
   projectId: 'example',
@@ -22,7 +29,7 @@ const workload = {
   artifact: { kind: 'image', image: 'example/backend@sha256:abc' },
   command: ['server'],
   args: ['--verbose'],
-  ports: [{ name: 'http', port: 8080, publishedPort: 18_080 }],
+  ports: { http: { port: 8080, publishedPort: 18_080 } },
   environment: {
     NODE_ENV: { kind: 'literal', value: 'production' },
     DB_PASSWORD: { kind: 'secret', reference },
@@ -45,36 +52,31 @@ const workload = {
       ],
     },
   },
-  files: [{ path: '/etc/backend/config.json', content: { kind: 'literal', value: '{}' } }],
+  files: { '/etc/backend/config.json': { kind: 'literal', value: '{}' } },
   health: { kind: 'http', port: 8080, path: '/health', intervalSeconds: 5 },
   resources: { cpuMillis: 500, memoryMiB: 256 },
-  persistence: [{ id: 'data', mountPath: '/data', sizeGiB: 10, retention: 'retain' }],
+  persistence: { data: { id: 'data', mountPath: '/data', sizeGiB: 10, retention: 'retain' } },
   exposure: 'public',
   replicas: 1,
-  dependsOn: ['database'],
+  dependsOn: { database: true },
 } as const satisfies InfraWorkloadSpec;
 
 const invalidWorkloads = [
   { artifact: { kind: 'build', dockerfile: 'Dockerfile' } },
   { artifact: { kind: 'image', image: '' } },
-  { ports: [{ name: 'http', port: 0 }] },
-  { ports: [{ name: 'http', port: 65536 }] },
-  { ports: [{ name: 'http', port: 1.5 }] },
-  { ports: [{ name: 'http', port: 80, protocol: 'sctp' }] },
-  {
-    ports: [
-      { name: 'http', port: 80 },
-      { name: 'http', port: 81 },
-    ],
-  },
+  { ports: { http: { port: 0 } } },
+  { ports: { http: { port: 65536 } } },
+  { ports: { http: { port: 1.5 } } },
+  { ports: { http: { port: 80, protocol: 'sctp' } } },
+  { ports: { '': { port: 80 } } },
   { replicas: -1 },
   { replicas: NaN },
   { replicas: 1.5 },
   { resources: { memoryMiB: Infinity } },
   { resources: { cpuMillis: 0 } },
-  { persistence: [{ id: 'data', mountPath: '/data', sizeGiB: 1 }] },
-  { persistence: [{ id: 'data', mountPath: '../data', sizeGiB: 1, retention: 'retain' }] },
-  { files: [{ path: '/etc/../secret', content: { kind: 'literal', value: 'x' } }] },
+  { persistence: { data: { id: 'data', mountPath: '/data', sizeGiB: 1 } } },
+  { persistence: { data: { id: 'data', mountPath: '../data', sizeGiB: 1, retention: 'retain' } } },
+  { files: { '/etc/../secret': { kind: 'literal', value: 'x' } } },
   { health: { kind: 'http', port: 80, path: '/health', failureThreshold: 0 } },
   { health: { kind: 'tcp', port: 80, path: '/health' } },
   { health: { kind: 'command', command: [] } },
@@ -134,7 +136,7 @@ describe('runtime-neutral workload boundary', () => {
       expect(
         isInfraEnvironmentSpec({
           deployment: { compute: { provider: 'local' }, runtime: { provider } },
-          workloads: [workload],
+          workloads: { backend: workload },
         }),
       ).toBe(true);
     }
@@ -156,11 +158,11 @@ describe('runtime-neutral workload boundary', () => {
     ).toBe(true);
   });
 
-  it('rejects duplicate workload identities', () => {
+  it('rejects workload registries whose key disagrees with workload id', () => {
     expect(
       isInfraEnvironmentSpec({
         deployment: { compute: { provider: 'local' }, runtime: { provider: 'k3s' } },
-        workloads: [workload, workload],
+        workloads: { duplicate: workload },
       }),
     ).toBe(false);
   });
@@ -266,7 +268,7 @@ describe('application state boundary', () => {
       category: 'developer_tools',
       themeId: 'default',
     },
-    themes: [],
+    themes: { default: defaultTheme },
     activeThemeId: 'default',
     screens: {},
     navigator: { type: 'stack', routes: [] },
@@ -276,7 +278,7 @@ describe('application state boundary', () => {
           deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
         },
       },
-      modules: [],
+      modules: {},
     },
     settings: { localization: { defaultLocale: 'en', locales: ['en'] } },
   } satisfies AppManifest;

package/src/infra.test.ts

@@ -23,7 +23,7 @@ const production = {
   },
   database: { provider: 'supabase' },
   auth: { provider: 'supabase' },
-  objectStorage: { provider: 'r2', buckets: ['media'] },
+  objectStorage: { provider: 'r2', buckets: { media: true } },
   authz: { provider: 'cerbos', kind: 'ABAC' },
   secretStore: { provider: 'supabase-vault' },
   networking: { domain: 'api.example.ch', publicBaseUrl: 'https://api.example.ch' },
@@ -33,7 +33,7 @@ describe('standalone Infra environments', () => {
   it('parses local/preview/production without an AppManifest or Deploy', () => {
     const manifest = {
       environments: { local, preview: production, production },
-      modules: [],
+      modules: {},
     } satisfies InfraManifest;
     expect(parseInfraManifest(JSON.parse(JSON.stringify(manifest)))).toEqual({
       ok: true,
@@ -45,14 +45,14 @@ describe('standalone Infra environments', () => {
   it.each([
     null,
     {},
-    { modules: [] },
-    { environments: {}, modules: [] },
-    { environments: { production }, modules: [] },
-    { environments: { local, staging: local }, modules: [] },
-    { environments: { local, preview: null }, modules: [] },
-    { environments: { local }, modules: [42] },
-    { environments: { local }, modules: [], modulesConfig: [] },
-    { environments: { local }, modules: [], apis: 'invalid' },
+    { modules: {} },
+    { environments: {}, modules: {} },
+    { environments: { production }, modules: {} },
+    { environments: { local, staging: local }, modules: {} },
+    { environments: { local, preview: null }, modules: {} },
+    { environments: { local }, modules: { invalid: 42 } },
+    { environments: { local }, modules: {}, modulesConfig: {} },
+    { environments: { local }, modules: {}, apis: 'invalid' },
   ])('rejects invalid environment boundaries: %j', (value) => {
     expect(isInfraManifest(value)).toBe(false);
     expect(parseInfraManifest(value).ok).toBe(false);
@@ -69,7 +69,7 @@ describe('standalone Infra environments', () => {
     'plugins',
     'pluginsConfig',
   ])('rejects removed top-level %s', (key) => {
-    expect(isInfraManifest({ environments: { local }, modules: [], [key]: {} })).toBe(false);
+    expect(isInfraManifest({ environments: { local }, modules: {}, [key]: {} })).toBe(false);
   });
 
   it.each(['storage', 'state', 'monitoring', 'observability', 'target'])(
@@ -148,21 +148,17 @@ describe('Cerbos policy configuration', () => {
         authz: {
           provider: 'cerbos',
           kind: 'ABAC',
-          policies: [{ path: 'app.yaml', content: 'apiVersion: api.cerbos.dev/v1' }],
+          policies: { 'app.yaml': 'apiVersion: api.cerbos.dev/v1' },
         },
       }),
     ).toBe(true);
   });
 
   it.each([
-    { policies: [{ path: '../app.yaml', content: 'x' }] },
-    {
-      policies: [
-        { path: 'app.yaml', content: 'x' },
-        { path: 'app.yaml', content: 'y' },
-      ],
-    },
-  ])('rejects unsafe or duplicate policy files: %j', ({ policies }) => {
+    { policies: { '../app.yaml': 'x' } },
+    { policies: { 'app.yaml': 42 } },
+    { policies: [{ path: 'app.yaml', content: 'legacy-array-shape' }] },
+  ])('rejects unsafe or non-canonical policy files: %j', ({ policies }) => {
     expect(
       isInfraEnvironmentSpec({
         ...local,

package/src/infraPersistence.test.ts

@@ -34,7 +34,7 @@ it('accepts scheduled database backups and an S3-backed Supabase storage service
         },
         objectStorage: {
           provider: 'supabase',
-          buckets: ['media'],
+          buckets: { media: true },
           backend: { ...target, bucket: 'ankhorage-storage' },
         },
       }),

package/src/infraServices.test.ts

@@ -12,7 +12,7 @@ const production = {
   },
   database: { provider: 'supabase' },
   auth: { provider: 'supabase' },
-  objectStorage: { provider: 'r2', buckets: ['media'] },
+  objectStorage: { provider: 'r2', buckets: { media: true } },
   authz: { provider: 'cerbos', kind: 'ABAC' },
   secretStore: { provider: 'supabase-vault' },
   networking: { domain: 'api.example.ch', publicBaseUrl: 'https://api.example.ch' },

package/src/requirements.test.ts

@@ -11,10 +11,10 @@ describe('platform requirements', () => {
   it('exports ebookReader as the canonical reader capability', () => {
     const capability: AnkhorageCapabilityName = 'ebookReader';
     const componentRequirements: ComponentRequirements = {
-      capabilities: [{ capability }],
+      capabilities: { [capability]: true },
     };
     const screenRequirements: ScreenRequirements = {
-      capabilities: [{ capability }],
+      capabilities: { [capability]: true },
     };
 
     expect(ANKHORAGE_CAPABILITY_NAMES).toContain(capability);

package/src/requirements.ts

@@ -1,3 +1,5 @@
+import type { SerializableSet } from './collections';
+
 export const ANKHORAGE_PERMISSION_NAMES = [
   'camera',
   'microphone',
@@ -24,20 +26,12 @@ export const ANKHORAGE_CAPABILITY_NAMES = [
 
 export type AnkhorageCapabilityName = (typeof ANKHORAGE_CAPABILITY_NAMES)[number];
 
-export interface ScreenPermissionRequirement {
-  readonly permission: AnkhoragePermissionName;
-}
-
-export interface ScreenCapabilityRequirement {
-  readonly capability: AnkhorageCapabilityName;
-}
-
 export interface ScreenRequirements {
-  readonly permissions?: readonly ScreenPermissionRequirement[];
-  readonly capabilities?: readonly ScreenCapabilityRequirement[];
+  readonly permissions?: SerializableSet<AnkhoragePermissionName>;
+  readonly capabilities?: SerializableSet<AnkhorageCapabilityName>;
 }
 
 export interface ComponentRequirements {
-  readonly permissions?: readonly ScreenPermissionRequirement[];
-  readonly capabilities?: readonly ScreenCapabilityRequirement[];
+  readonly permissions?: SerializableSet<AnkhoragePermissionName>;
+  readonly capabilities?: SerializableSet<AnkhorageCapabilityName>;
 }

package/src/secrets.test.ts

@@ -67,7 +67,7 @@ describe('secret-store contracts', () => {
     };
 
     const infra: InfraManifest = {
-      modules: [],
+      modules: {},
       environments: {
         local: {
           deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },

package/src/serializable.ts

@@ -0,0 +1,25 @@
+import { isRecord } from '@ankhorage/utility/object';
+
+export type SerializableValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly SerializableValue[]
+  | {
+      readonly [key: string]: SerializableValue;
+    };
+
+/*** Validate recursively serializable manifest/config values without accepting functions or host objects. */
+export function isSerializableValue(value: unknown): value is SerializableValue {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return true;
+  }
+  if (Array.isArray(value)) return value.every(isSerializableValue);
+  return isRecord(value) && Object.values(value).every(isSerializableValue);
+}

package/src/state.ts

@@ -1,3 +1,5 @@
+import type { SerializableValue } from './serializable';
+
 /** Legend currently implements in-memory state only; unsupported persistence cannot be selected. */
 export interface AppStateSpec {
   readonly provider: 'legend';
@@ -6,12 +8,7 @@ export interface AppStateSpec {
 
 export type StatePrimitive = string | number | boolean | null;
 
-export type StateValue =
-  | StatePrimitive
-  | readonly StateValue[]
-  | {
-      readonly [key: string]: StateValue;
-    };
+export type StateValue = SerializableValue;
 
 export type StatePath = string | readonly string[];
 

package/src/types/infraManifest.ts

@@ -1,10 +1,11 @@
 import type { AuthFlowConfig, AuthOAuthConfig } from '../auth';
-import type { ApiDefinitionList } from '../data';
+import type { SerializableSet } from '../collections';
+import type { ApiDefinitionRegistry, DataContractValue } 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';
+import type { InfraWorkloadRegistry } from './infraWorkload';
 
 export type InfraAdapterId = keyof typeof INFRA_ADAPTER_CATALOG;
 export type InfraCapability =
@@ -86,11 +87,11 @@ export interface InfraDatabaseConfigMap {
 }
 export interface InfraObjectStorageConfigMap {
   readonly supabase: {
-    readonly buckets?: readonly string[];
+    readonly buckets?: SerializableSet;
     readonly backend?: InfraS3PersistenceTarget;
   };
   readonly r2: {
-    readonly buckets?: readonly string[];
+    readonly buckets?: SerializableSet;
     readonly accountId?: string;
     readonly credentials?: InfraControlPlaneCredentialRef;
   };
@@ -108,13 +109,9 @@ export interface InfraAuthConfigMap {
 export interface InfraAuthzConfigMap {
   readonly cerbos: {
     readonly kind: 'RBAC' | 'ABAC';
-    readonly policies?: readonly InfraAuthzPolicyFile[];
+    readonly policies?: Readonly<Record<string, string>>;
   };
 }
-export interface InfraAuthzPolicyFile {
-  readonly path: string;
-  readonly content: string;
-}
 export interface InfraSecretStoreConfigMap {
   readonly 'supabase-vault': { readonly schema?: string };
 }
@@ -161,15 +158,22 @@ export interface InfraEnvironmentSpec {
   readonly authz?: InfraAuthzSpec;
   readonly secretStore?: InfraSecretStoreSpec;
   readonly networking?: InfraNetworkingSpec;
-  readonly workloads?: readonly InfraWorkloadSpec[];
+  readonly workloads?: InfraWorkloadRegistry;
 }
 
+export type InfraModuleId = string;
+
+export interface InfraModuleSpec {
+  readonly config?: DataContractValue;
+}
+
+export type InfraModuleRegistry = Readonly<Record<InfraModuleId, InfraModuleSpec>>;
+
 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>>;
+  readonly apis?: ApiDefinitionRegistry;
+  readonly modules: InfraModuleRegistry;
 }

package/src/types/infraWorkload.ts

@@ -1,3 +1,4 @@
+import type { SerializableSet } from '../collections';
 import type { InfraControlPlaneCredentialRef, InfraSecretReference } from './infraSecrets';
 
 export interface InfraWorkloadArtifact {
@@ -25,7 +26,6 @@ export type InfraWorkloadValue =
     };
 
 export interface InfraWorkloadPort {
-  readonly name: string;
   readonly port: number;
   readonly protocol?: 'tcp' | 'udp';
   /** Exact external listener port requested for a public single-replica workload. */
@@ -57,25 +57,26 @@ export interface InfraWorkloadVolumeSpec {
   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 type InfraWorkloadId = string;
+export type InfraWorkloadPortRegistry = Readonly<Record<string, InfraWorkloadPort>>;
+export type InfraWorkloadFileMap = Readonly<Record<string, InfraWorkloadValue>>;
+export type InfraWorkloadVolumeRegistry = Readonly<Record<string, InfraWorkloadVolumeSpec>>;
 
 export interface InfraWorkloadSpec {
-  readonly id: string;
+  readonly id: InfraWorkloadId;
   readonly artifact: InfraWorkloadArtifact;
   readonly command?: readonly string[];
   readonly args?: readonly string[];
-  readonly ports?: readonly InfraWorkloadPort[];
+  readonly ports?: InfraWorkloadPortRegistry;
   readonly environment?: Readonly<Record<string, InfraWorkloadValue>>;
-  readonly files?: readonly InfraWorkloadFileSpec[];
+  readonly files?: InfraWorkloadFileMap;
   readonly health?: InfraWorkloadHealthSpec;
   readonly resources?: InfraWorkloadResourceSpec;
-  readonly persistence?: readonly InfraWorkloadVolumeSpec[];
+  readonly persistence?: InfraWorkloadVolumeRegistry;
   readonly exposure?: 'internal' | 'public';
   readonly replicas?: number;
   /** IDs in the composed desired-state graph; the orchestrator validates missing/cyclic edges. */
-  readonly dependsOn?: readonly string[];
+  readonly dependsOn?: SerializableSet;
 }
+
+export type InfraWorkloadRegistry = Readonly<Record<InfraWorkloadId, InfraWorkloadSpec>>;