@ankhorage/contracts 21.0.0 → 22.0.1

package/src/appManifest/screens.ts

@@ -2,8 +2,10 @@ import { COLOR_HARMONIES } from '@ankhorage/color-theory';
 import { isRecord } from '@ankhorage/utility/object';
 import { isOptionalString } from '@ankhorage/utility/string';
 
+import { isSerializableSet } from '../collections';
 import { isMediaAssetReference } from '../media';
-import { APP_CATEGORIES } from '../types';
+import { ANKHORAGE_CAPABILITY_NAMES, ANKHORAGE_PERMISSION_NAMES } from '../requirements';
+import { APP_CATEGORIES, type ThemeRegistry } from '../types';
 import { isBindingValueSource, isScreenDataLoaderDefinition } from './bindings';
 
 export { isAppNavigatorManifest } from './navigator';
@@ -11,6 +13,8 @@ export { isAppNavigatorManifest } from './navigator';
 const APP_CATEGORY_SET = new Set<string>(APP_CATEGORIES);
 const COLOR_HARMONY_SET = new Set<string>(COLOR_HARMONIES);
 const SPLASH_SCREEN_RESIZE_MODE_SET = new Set<string>(['contain', 'cover', 'native']);
+const PERMISSION_NAME_SET = new Set<string>(ANKHORAGE_PERMISSION_NAMES);
+const CAPABILITY_NAME_SET = new Set<string>(ANKHORAGE_CAPABILITY_NAMES);
 
 /*** Validate application identity and optional authored metadata. */
 export function isManifestMetadata(value: unknown): boolean {
@@ -28,7 +32,7 @@ export function isManifestMetadata(value: unknown): boolean {
 }
 
 /*** Validate theme identity and its required light and dark modes. */
-export function isThemeConfig(value: unknown): boolean {
+function isThemeConfig(value: unknown): boolean {
   return (
     isRecord(value) &&
     typeof value.id === 'string' &&
@@ -38,6 +42,16 @@ export function isThemeConfig(value: unknown): boolean {
   );
 }
 
+/*** Validate themes in the authored theme registry and require registry keys to match theme identity. */
+export function isThemeRegistry(value: unknown): value is ThemeRegistry {
+  return (
+    isRecord(value) &&
+    Object.entries(value).every(
+      ([registryKey, theme]) => isThemeConfig(theme) && isRecord(theme) && registryKey === theme.id,
+    )
+  );
+}
+
 /*** Validate screens in the authored screen registry. */
 export function isScreenRegistry(value: unknown): boolean {
   return (
@@ -127,15 +141,12 @@ function isSplashScreenModeSpec(value: unknown): boolean {
 function isScreenRequirements(value: unknown): boolean {
   return (
     isRecord(value) &&
-    (value.permissions === undefined || isRequirementArray(value.permissions, 'permission')) &&
-    (value.capabilities === undefined || isRequirementArray(value.capabilities, 'capability'))
+    (value.permissions === undefined || isRequirementSet(value.permissions, PERMISSION_NAME_SET)) &&
+    (value.capabilities === undefined || isRequirementSet(value.capabilities, CAPABILITY_NAME_SET))
   );
 }
 
-/*** Validate the entries of a capability or permission requirement list. */
-function isRequirementArray(value: unknown, key: 'capability' | 'permission'): boolean {
-  return (
-    Array.isArray(value) &&
-    value.every((entry) => isRecord(entry) && typeof entry[key] === 'string')
-  );
+/*** Validate unordered requirement membership against the supported capability or permission names. */
+function isRequirementSet(value: unknown, allowedNames: ReadonlySet<string>): boolean {
+  return isSerializableSet(value) && Object.keys(value).every((name) => allowedNames.has(name));
 }

package/src/appManifest/splashScreen.test.ts

@@ -3,7 +3,7 @@ import { describe, expect, it } from 'bun:test';
 import type { AppManifest, SplashScreenSpec } from '../index';
 
 describe('AppManifest splash screen contract', () => {
-  it('accepts portable media references with Expo-owned option types', () => {
+  it('accepts portable media references with the canonical splash option shape', () => {
     const splashScreen: SplashScreenSpec = {
       backgroundColor: '#ffffff',
       image: { mediaId: 'splash-logo' },
@@ -23,13 +23,13 @@ describe('AppManifest splash screen contract', () => {
   it('keeps root-only Expo options out of dark-mode overrides', () => {
     const splashWithDarkImageWidth: SplashScreenSpec = {
       dark: {
-        // @ts-expect-error Expo dark-mode options do not include image sizing.
+        // @ts-expect-error Dark-mode overrides do not include image sizing.
         imageWidth: 160,
       },
     };
     const splashWithDarkResizeMode: SplashScreenSpec = {
       dark: {
-        // @ts-expect-error Expo dark-mode options do not include resize mode.
+        // @ts-expect-error Dark-mode overrides do not include resize mode.
         resizeMode: 'contain',
       },
     };

package/src/appManifest/splashScreen.ts

@@ -1,24 +1,14 @@
-import type { Props as ExpoSplashScreenPluginProps } from 'expo-splash-screen/plugin';
-
 import type { MediaAssetReference } from '../media';
 
-type ExpoSplashScreenRootProps = Pick<
-  ExpoSplashScreenPluginProps,
-  'backgroundColor' | 'image' | 'imageWidth' | 'resizeMode'
->;
+export type SplashScreenResizeMode = 'contain' | 'cover' | 'native';
 
-type PortableSplashScreenProps<T extends { readonly image?: string }> = Readonly<
-  Omit<T, 'image'>
-> & {
+export interface SplashScreenModeSpec {
+  readonly backgroundColor?: string;
   readonly image?: MediaAssetReference;
-};
-
-export type SplashScreenResizeMode = NonNullable<ExpoSplashScreenPluginProps['resizeMode']>;
-
-export type SplashScreenModeSpec = PortableSplashScreenProps<
-  NonNullable<ExpoSplashScreenPluginProps['dark']>
->;
+}
 
-export type SplashScreenSpec = PortableSplashScreenProps<ExpoSplashScreenRootProps> & {
+export interface SplashScreenSpec extends SplashScreenModeSpec {
+  readonly imageWidth?: number;
+  readonly resizeMode?: SplashScreenResizeMode;
   readonly dark?: SplashScreenModeSpec;
-};
+}

package/src/appManifest.test.ts

@@ -1,3 +1,4 @@
+import { readOwnProperty } from '@ankhorage/utility/object';
 import { describe, expect, it } from 'bun:test';
 
 import { isAppManifest, parseAppManifest } from './appManifest';
@@ -11,14 +12,14 @@ function createManifest(): Record<string, unknown> {
       category: 'developer_tools',
       themeId: 'default',
     },
-    themes: [
-      {
+    themes: {
+      default: {
         id: 'default',
         name: 'Default',
         light: { primaryColor: '#3366ff', harmony: 'analogous' },
         dark: { primaryColor: '#6699ff', harmony: 'analogous' },
       },
-    ],
+    },
     activeThemeId: 'default',
     activeThemeMode: 'light',
     splashScreen: {
@@ -43,12 +44,12 @@ function createManifest(): Record<string, unknown> {
         local: {
           deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
           database: { provider: 'supabase', tier: 'dev' },
-          objectStorage: { provider: 'supabase', buckets: ['media'] },
+          objectStorage: { provider: 'supabase', buckets: { media: true } },
           networking: { domain: 'example.test' },
         },
       },
-      apis: [
-        {
+      apis: {
+        nutrition: {
           id: 'nutrition',
           origin: 'external',
           protocol: 'rest',
@@ -81,9 +82,10 @@ function createManifest(): Record<string, unknown> {
             },
           },
         },
-      ],
-      modules: ['expo-localization'],
-      modulesConfig: { localization: { defaultLocale: 'en' } },
+      },
+      modules: {
+        'expo-localization': { config: { defaultLocale: 'en' } },
+      },
     },
     navigator: {
       type: 'stack',
@@ -120,8 +122,8 @@ function createManifest(): Record<string, unknown> {
           },
         ],
         requires: {
-          permissions: [{ permission: 'camera' }],
-          capabilities: [{ capability: 'barcodeScanner' }, { capability: 'ebookReader' }],
+          permissions: { camera: true },
+          capabilities: { barcodeScanner: true, ebookReader: true },
         },
       },
     },
@@ -199,8 +201,9 @@ describe('AppManifest runtime parsing', () => {
 
   it('rejects malformed nested canonical structures', () => {
     const manifest = createManifest();
-    const themes = manifest.themes as Record<string, unknown>[];
-    const light = themes[0]?.light as Record<string, unknown>;
+    const themes = manifest.themes as Record<string, unknown>;
+    const theme = readOwnProperty<Record<string, unknown>>(themes, 'default');
+    const light = theme?.light as Record<string, unknown>;
     light.harmony = 'not-a-harmony';
 
     expect(parseAppManifest(manifest)).toEqual({
@@ -209,11 +212,13 @@ describe('AppManifest runtime parsing', () => {
     });
   });
 
-  it('rejects duplicate canonical API ids', () => {
+  it('rejects API registries whose key disagrees with API id', () => {
     const manifest = createManifest();
     const infra = manifest.infra as Record<string, unknown>;
-    const apis = infra.apis as Record<string, unknown>[];
-    apis.push(structuredClone(apis[0]));
+    const apis = infra.apis as Record<string, unknown>;
+    const nutrition = readOwnProperty(apis, 'nutrition');
+    apis.catalog = nutrition;
+    delete apis.nutrition;
 
     expect(isAppManifest(manifest)).toBe(false);
   });

package/src/bindings.test.ts

@@ -1,3 +1,4 @@
+import { readOwnProperty } from '@ankhorage/utility/object';
 import { describe, expect, it } from 'bun:test';
 
 import type {
@@ -474,8 +475,8 @@ describe('component data-binding contracts', () => {
         category: 'developer_tools',
         themeId: 'default',
       },
-      themes: [
-        {
+      themes: {
+        default: {
           id: 'default',
           name: 'Default',
           light: {
@@ -487,7 +488,7 @@ describe('component data-binding contracts', () => {
             harmony: 'analogous',
           },
         },
-      ],
+      },
       activeThemeId: 'default',
       infra: {
         environments: {
@@ -495,8 +496,8 @@ describe('component data-binding contracts', () => {
             deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
           },
         },
-        apis: [
-          {
+        apis: {
+          cms: {
             id: 'cms',
             origin: 'external',
             protocol: 'rest',
@@ -519,8 +520,8 @@ describe('component data-binding contracts', () => {
               },
             },
           },
-        ],
-        modules: [],
+        },
+        modules: {},
       },
       navigator: {
         type: 'stack',
@@ -566,6 +567,8 @@ describe('component data-binding contracts', () => {
 
     assertSerializable(manifest);
     expect(manifest.dataBindings?.['hero-title']?.props?.children?.source.kind).toBe('operation');
-    expect(manifest.infra.apis?.[0]?.id).toBe('cms');
+    expect(manifest.infra.apis ? readOwnProperty(manifest.infra.apis, 'cms')?.id : undefined).toBe(
+      'cms',
+    );
   });
 });

package/src/bindings.ts

@@ -1,17 +1,10 @@
 import type { ApiId, EndpointId, OperationId } from './data';
+import type { SerializableValue } from './serializable';
 
 export type ComponentInstanceId = string;
 export type ComponentTypeId = string;
 
-export type BindingValue =
-  | string
-  | number
-  | boolean
-  | null
-  | readonly BindingValue[]
-  | {
-      readonly [key: string]: BindingValue;
-    };
+export type BindingValue = SerializableValue;
 
 export type BindingDataPath = string;
 

package/src/collections.ts

@@ -0,0 +1,8 @@
+import { isRecord } from '@ankhorage/utility/object';
+
+export type SerializableSet<T extends string = string> = Readonly<Partial<Record<T, true>>>;
+
+/*** Validate the canonical JSON-safe representation for unordered string membership. */
+export function isSerializableSet(value: unknown): value is SerializableSet {
+  return isRecord(value) && Object.values(value).every((member) => member === true);
+}

package/src/contracts.test.ts

@@ -260,10 +260,11 @@ describe('contracts', () => {
             deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
           },
         },
-        modules: [],
-        modulesConfig: {
-          localization: {
-            defaultLocale: 'en',
+        modules: {
+          'expo-localization': {
+            config: {
+              defaultLocale: 'en',
+            },
           },
         },
       },
@@ -273,10 +274,11 @@ describe('contracts', () => {
       state,
       infra: {
         environments: manifest.infra.environments,
-        modules: [],
-        modulesConfig: {
-          localization: {
-            defaultLocale: 'en',
+        modules: {
+          'expo-localization': {
+            config: {
+              defaultLocale: 'en',
+            },
           },
         },
       },
@@ -295,11 +297,12 @@ describe('contracts', () => {
           deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
         },
       },
-      modules: ['expo-localization'],
-      modulesConfig: {
+      modules: {
         'expo-localization': {
-          defaultLocale: 'en',
-          locales: ['en', 'de'],
+          config: {
+            defaultLocale: 'en',
+            locales: ['en', 'de'],
+          },
         },
       },
     };
@@ -311,7 +314,7 @@ describe('contracts', () => {
 
     expect(hasLegacyModules).toBe(false);
     expect(hasLegacyModulesConfig).toBe(false);
-    expect(Object.keys(infra).sort()).toEqual(['environments', 'modules', 'modulesConfig']);
+    expect(Object.keys(infra).sort()).toEqual(['environments', 'modules']);
     expect(expoConfig.plugins).toEqual(['expo-router']);
   });
 

package/src/data/apis.test.ts

@@ -1,7 +1,8 @@
+import { readOwnProperty } from '@ankhorage/utility/object';
 import { describe, expect, it } from 'bun:test';
 
 import type {
-  ApiDefinitionList,
+  ApiDefinitionRegistry,
   ExternalRestApiDefinition,
   InternalRestApiDefinition,
 } from './apis';
@@ -56,11 +57,12 @@ describe('canonical API contracts', () => {
     expect(api.endpoints.products?.operations['products.list']?.method).toBe('GET');
   });
 
-  it('stores canonical APIs as an ordered infra list', () => {
-    const apis: ApiDefinitionList = [createNutritionApi()];
+  it('stores canonical APIs in an identity-keyed registry', () => {
+    const api = createNutritionApi();
+    const apis: ApiDefinitionRegistry = { [api.id]: api };
 
     assertSerializable(apis);
-    expect(apis[0]?.id).toBe('nutrition');
+    expect(readOwnProperty<ApiDefinitionRegistry[string]>(apis, 'nutrition')?.id).toBe('nutrition');
   });
 
   it('reserves an internal REST API identity without persistence implementation', () => {

package/src/data/apis.ts

@@ -60,4 +60,4 @@ export interface InternalRestApiDefinition extends ApiBaseDefinition {
 export type ApiDefinition =
   ExternalGraphQlApiDefinition | ExternalRestApiDefinition | InternalRestApiDefinition;
 
-export type ApiDefinitionList = readonly ApiDefinition[];
+export type ApiDefinitionRegistry = Readonly<Record<ApiId, ApiDefinition>>;

package/src/data/values.ts

@@ -1,11 +1,5 @@
-export type DataContractValue =
-  | string
-  | number
-  | boolean
-  | null
-  | readonly DataContractValue[]
-  | {
-      readonly [key: string]: DataContractValue;
-    };
+import type { SerializableValue } from '../serializable';
+
+export type DataContractValue = SerializableValue;
 
 export type DataPath = string;

package/src/deploy.test.ts

@@ -17,14 +17,14 @@ function createManifest(deploy?: unknown): Record<string, unknown> {
       category: 'developer_tools',
       themeId: 'default',
     },
-    themes: [
-      {
+    themes: {
+      default: {
         id: 'default',
         name: 'Default',
         light: { primaryColor: '#3366ff', harmony: 'analogous' },
         dark: { primaryColor: '#6699ff', harmony: 'analogous' },
       },
-    ],
+    },
     activeThemeId: 'default',
     ...(deploy === undefined ? {} : { deploy }),
     infra: {
@@ -33,7 +33,7 @@ function createManifest(deploy?: unknown): Record<string, unknown> {
           deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
         },
       },
-      modules: [],
+      modules: {},
     },
     navigator: { type: 'stack', routes: [] },
     screens: {},

package/src/index.ts

@@ -2,6 +2,7 @@ export * from './appManifest';
 export * from './auth';
 export * from './bindings';
 export * from './cli';
+export * from './collections';
 export * from './data';
 export * from './db';
 export * from './deploy';
@@ -14,6 +15,7 @@ export * from './repository';
 export * from './requirements';
 export * from './runtimeCallbacks';
 export * from './secrets';
+export * from './serializable';
 export * from './state';
 export * from './storage';
 export * from './theme';

package/src/infra/isInfraEnvironmentSpec.ts

@@ -1,6 +1,7 @@
 import { isRecord } from '@ankhorage/utility/object';
 import { isNonEmptyString } from '@ankhorage/utility/string';
 
+import { isSerializableSet } from '../collections';
 import type {
   InfraEnvironmentSpec,
   InfraObjectStorageSpec,
@@ -92,16 +93,14 @@ function hasNetworkingRelationships(value: InfraEnvironmentSpec): boolean {
 /*** Validate portable, unique Cerbos policy files without host paths or traversal. */
 function isPolicyFiles(value: unknown): boolean {
   return (
-    Array.isArray(value) &&
-    value.every((policy) =>
-      isInfraShape(policy, {
-        path: (path) =>
-          isNonEmptyString(path) && !path.startsWith('/') && !path.split('/').includes('..'),
-        content: isNonEmptyString,
-      }),
-    ) &&
-    new Set(value.map((policy) => (isRecord(policy) ? policy.path : undefined))).size ===
-      value.length
+    isRecord(value) &&
+    Object.entries(value).every(
+      ([path, content]) =>
+        isNonEmptyString(path) &&
+        !path.startsWith('/') &&
+        !path.split('/').includes('..') &&
+        isNonEmptyString(content),
+    )
   );
 }
 
@@ -133,7 +132,7 @@ function isObjectStorage(value: unknown): boolean {
   if (!isRecord(value)) return false;
   const common = {
     provider: (provider: unknown) => provider === value.provider,
-    buckets: infraFields.optionalStrings,
+    buckets: (buckets: unknown) => buckets === undefined || isSerializableSet(buckets),
   };
   if (value.provider === 'supabase') {
     return isInfraShape(value, {
@@ -153,16 +152,17 @@ function isObjectStorage(value: unknown): boolean {
 /*** 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
+    isRecord(value) &&
+    Object.entries(value).every(
+      ([workloadId, workload]) => isInfraWorkloadSpec(workload) && workload.id === workloadId,
+    )
   );
 }
 
 /*** Prevent two workloads in one environment from claiming the same external listener. */
 function hasUniquePublishedPorts(value: InfraEnvironmentSpec): boolean {
-  const ports = (value.workloads ?? []).flatMap((workload) =>
-    (workload.ports ?? []).flatMap(({ publishedPort }) =>
+  const ports = Object.values(value.workloads ?? {}).flatMap((workload) =>
+    Object.values(workload.ports ?? {}).flatMap(({ publishedPort }) =>
       publishedPort === undefined ? [] : [publishedPort],
     ),
   );

package/src/infra/isInfraManifest.ts

@@ -1,10 +1,10 @@
 import { isRecord } from '@ankhorage/utility/object';
 
-import { isApiDefinitionList } from '../appManifest/apis';
+import { isApiDefinitionRegistry } from '../appManifest/apis';
 import { APP_ENVIRONMENT_IDS } from '../environments';
-import type { InfraManifest } from '../types/infraManifest';
+import { isSerializableValue } from '../serializable';
+import type { InfraManifest, InfraModuleSpec } from '../types/infraManifest';
 import type { InfraShape } from '../types/infraValidation';
-import { infraFields } from './infraFields';
 import { isInfraEnvironmentSpec } from './isInfraEnvironmentSpec';
 import { isInfraShape } from './isInfraShape';
 
@@ -12,9 +12,8 @@ import { isInfraShape } from './isInfraShape';
 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),
+    apis: (apis) => apis === undefined || isApiDefinitionRegistry(apis),
+    modules: isModuleRegistry,
   } satisfies InfraShape<InfraManifest>);
 }
 
@@ -27,3 +26,15 @@ function isEnvironments(value: unknown): boolean {
       ((environment === undefined && key !== 'local') || isInfraEnvironmentSpec(environment)),
   );
 }
+
+/*** Validate installed module identity and optional serializable module-owned configuration. */
+function isModuleRegistry(value: unknown): boolean {
+  return isRecord(value) && Object.values(value).every(isModuleSpec);
+}
+
+/*** Validate one module registry entry. */
+function isModuleSpec(value: unknown): value is InfraModuleSpec {
+  return isInfraShape(value, {
+    config: (config) => config === undefined || isSerializableValue(config),
+  });
+}