@ankhorage/contracts 21.0.0 → 22.0.0

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

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;