@ankhorage/contracts 20.0.0 → 22.0.0

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-types.test.ts

@@ -8,8 +8,10 @@ import type {
   InfraComputeAdapter,
   InfraComputeSnapshot,
   InfraControlPlaneCredentialRef,
+  InfraCredentialPort,
   InfraDeploymentSpec,
   InfraDestroyRequest,
+  InfraExecutionContext,
   InfraManifest,
   InfraObjectStorageSpec,
   InfraOutput,
@@ -17,6 +19,7 @@ import type {
   InfraRuntimeAdapter,
   InfraRuntimeDesiredState,
   InfraRuntimeProviderId,
+  InfraServiceAdapter,
 } from './infra';
 import type { AppStateSpec } from './state';
 
@@ -122,3 +125,27 @@ it('requires read-only compute discovery separately from mutating ensure', () =>
 
   expect(computeBoundary).toEqual([true, true]);
 });
+
+it('shares one generic credential port and optional service preparation lifecycle', () => {
+  type CredentialBundle = Readonly<Record<string, string>>;
+  type Service = InfraServiceAdapter;
+
+  const boundary: readonly [
+    Assignable<InfraExecutionContext['credentials'], InfraCredentialPort>,
+    Assignable<
+      Awaited<ReturnType<InfraCredentialPort['findAsync']>>,
+      InfraResult<CredentialBundle | null>
+    >,
+    Assignable<
+      Awaited<ReturnType<InfraCredentialPort['resolveAsync']>>,
+      InfraResult<CredentialBundle>
+    >,
+    Assignable<Awaited<ReturnType<InfraCredentialPort['persistAsync']>>, InfraResult<null>>,
+    Assignable<
+      Exclude<Service['prepareAsync'], undefined>,
+      (context: InfraExecutionContext) => Promise<InfraResult<null>>
+    >,
+  ] = [true, true, true, true, true];
+
+  expect(boundary).toEqual([true, true, true, true, true]);
+});

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/infraAdapters.ts

@@ -29,6 +29,23 @@ export type InfraAdapterDescriptor<P extends InfraAdapterId = InfraAdapterId> =
   };
 }[P];
 
+/** Trusted execution-only control-plane credential lookup, resolution and persistence. */
+export interface InfraCredentialPort {
+  /** Return a credential bundle when present; absence is not an error. */
+  findAsync(
+    reference: InfraControlPlaneCredentialRef,
+  ): Promise<InfraResult<Readonly<Record<string, string>> | null>>;
+  /** Resolve a required credential bundle; absence is an error. */
+  resolveAsync(
+    reference: InfraControlPlaneCredentialRef,
+  ): Promise<InfraResult<Readonly<Record<string, string>>>>;
+  /** Persist an opaque provider-owned credential bundle without exposing its schema to the host. */
+  persistAsync(
+    reference: InfraControlPlaneCredentialRef,
+    values: Readonly<Record<string, string>>,
+  ): Promise<InfraResult<null>>;
+}
+
 /** Trusted execution-only ports. Implementations must not serialize resolved credential values. */
 export interface InfraExecutionContext {
   readonly projectId: string;
@@ -36,11 +53,7 @@ export interface InfraExecutionContext {
   readonly desired: InfraEnvironmentSpec;
   readonly previous?: InfraLedger;
   readonly signal?: AbortSignal;
-  readonly credentials: {
-    resolveAsync(
-      reference: InfraControlPlaneCredentialRef,
-    ): Promise<InfraResult<Readonly<Record<string, string>>>>;
-  };
+  readonly credentials: InfraCredentialPort;
   readonly secrets: {
     resolveAsync(reference: InfraSecretReference): Promise<InfraResult<string>>;
   };
@@ -133,6 +146,8 @@ export interface InfraServiceAdapter {
   /** Read-only service config, bootstrap credentials and dependency validation. */
   validateAsync(context: InfraExecutionContext): Promise<InfraResult<null>>;
   planAsync(context: InfraExecutionContext): Promise<InfraResult<readonly InfraPlanAction[]>>;
+  /** Mutating pre-runtime preparation invoked only by an orchestrated `up` operation. */
+  prepareAsync?(context: InfraExecutionContext): Promise<InfraResult<null>>;
   desiredWorkloadsAsync(
     context: InfraExecutionContext,
   ): Promise<InfraResult<readonly InfraWorkloadSpec[]>>;

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>>;

package/src/types.ts

@@ -14,6 +14,7 @@ import type { MediaAssetReference, MediaManifest } from './media';
 import type { AppNavigatorManifest } from './navigator';
 import type { RepositoryManifest } from './repository';
 import type { ScreenRequirements } from './requirements';
+import type { SerializableValue } from './serializable';
 import type { AppStateSpec } from './state';
 import type { ThemeGlobalTokenOverrides, ThemeRecipeOverrides } from './theme';
 
@@ -22,8 +23,10 @@ export interface ThemeModeConfig {
   harmony: ColorHarmony;
 }
 
+export type ThemeId = string;
+
 export interface ThemeConfig {
-  id: string;
+  id: ThemeId;
   name: string;
   light: ThemeModeConfig;
   dark: ThemeModeConfig;
@@ -33,6 +36,8 @@ export interface ThemeConfig {
   recipes?: ThemeRecipeOverrides;
 }
 
+export type ThemeRegistry = Readonly<Record<ThemeId, ThemeConfig>>;
+
 export type ActionType =
   'navigate' | 'alert' | 'console' | 'toggleDarkMode' | 'setLanguage' | 'search' | 'filter';
 
@@ -93,13 +98,7 @@ export type Action =
   | SetLanguageAction
   | ToggleDarkModeAction;
 
-export type ManifestValue =
-  | string
-  | number
-  | boolean
-  | null
-  | readonly ManifestValue[]
-  | { readonly [key: string]: ManifestValue };
+export type ManifestValue = SerializableValue;
 
 export type ComponentEventPayloadValue = ManifestValue;
 
@@ -271,12 +270,12 @@ export interface AppManifest {
     slug: string;
     version: string;
     category: AppCategory;
-    themeId: string;
+    themeId: ThemeId;
     created?: string;
     updated?: string;
   };
-  themes: ThemeConfig[];
-  activeThemeId: string;
+  themes: ThemeRegistry;
+  activeThemeId: ThemeId;
   activeThemeMode?: 'dark' | 'light';
   splashScreen?: SplashScreenSpec;
   /** Studio-managed authoring media. Runtime/user uploads are intentionally separate. */
@@ -287,7 +286,7 @@ export interface AppManifest {
   state?: AppStateSpec;
   infra: InfraManifest;
   navigator: AppNavigatorManifest;
-  screens: Record<string, ScreenSpec>;
+  screens: Readonly<Record<string, ScreenSpec>>;
   dataSources?: DataSourceRegistry;
   dataBindings?: ComponentDataBindingRegistry;
   repository?: RepositoryManifest;