@ankhorage/contracts 13.0.1 → 15.0.0

package/src/appManifest/media.ts

@@ -1,3 +1,6 @@
+import { hasOnlyKeys, isRecord } from '@ankhorage/utility/object';
+import { isNonEmptyString, isOptionalString } from '@ankhorage/utility/string';
+
 import {
   MEDIA_ASSET_KINDS,
   type MediaAsset,
@@ -5,10 +8,10 @@ import {
   type MediaAssetSource,
   type MediaManifest,
 } from '../media';
-import { isOptionalString, isRecord } from './shared';
 
 const MEDIA_ASSET_KIND_SET = new Set<string>(MEDIA_ASSET_KINDS);
 
+/*** Validate authored media assets and their registry identity. */
 export function isMediaManifest(value: unknown): value is MediaManifest {
   if (!isRecord(value) || !hasOnlyKeys(value, ['assets']) || !isRecord(value.assets)) return false;
 
@@ -17,6 +20,7 @@ export function isMediaManifest(value: unknown): value is MediaManifest {
   );
 }
 
+/*** Validate media identity, kind, source and optional metadata. */
 function isMediaAsset(value: unknown): value is MediaAsset {
   return (
     isRecord(value) &&
@@ -31,6 +35,7 @@ function isMediaAsset(value: unknown): value is MediaAsset {
   );
 }
 
+/*** Validate the selected bundled, URL or storage-backed media source. */
 function isMediaAssetSource(value: unknown): value is MediaAssetSource {
   if (!isRecord(value) || typeof value.kind !== 'string') return false;
 
@@ -52,6 +57,7 @@ function isMediaAssetSource(value: unknown): value is MediaAssetSource {
   );
 }
 
+/*** Validate optional descriptive and numeric media metadata. */
 function isMediaAssetMetadata(value: unknown): value is MediaAssetMetadata {
   return (
     isRecord(value) &&
@@ -72,10 +78,12 @@ function isMediaAssetMetadata(value: unknown): value is MediaAssetMetadata {
   );
 }
 
+/*** Validate an authored HTTP or HTTPS media URL. */
 function isStableRemoteUrl(value: unknown): boolean {
   return typeof value === 'string' && /^https?:\/\//iu.test(value.trim());
 }
 
+/*** Validate a portable bundled-media path. */
 function isBundledPath(value: unknown): boolean {
   if (!isNonEmptyString(value)) return false;
   const path = value.trim();
@@ -83,19 +91,12 @@ function isBundledPath(value: unknown): boolean {
   return !path.split('/').includes('..');
 }
 
-function isNonEmptyString(value: unknown): value is string {
-  return typeof value === 'string' && value.trim().length > 0;
-}
-
+/*** Accept an omitted media metric or a finite non-negative number. */
 function isOptionalFiniteNonNegativeNumber(value: unknown): boolean {
   return value === undefined || (typeof value === 'number' && Number.isFinite(value) && value >= 0);
 }
 
+/*** Accept an omitted media metric or a finite positive number. */
 function isOptionalFinitePositiveNumber(value: unknown): boolean {
   return value === undefined || (typeof value === 'number' && Number.isFinite(value) && value > 0);
 }
-
-function hasOnlyKeys(value: Record<string, unknown>, allowedKeys: readonly string[]): boolean {
-  const allowed = new Set(allowedKeys);
-  return Object.keys(value).every((key) => allowed.has(key));
-}

package/src/appManifest/navigator.ts

@@ -1,14 +1,16 @@
+import { isStringArray } from '@ankhorage/utility/array';
+import { hasOnlyKeys, isRecord } from '@ankhorage/utility/object';
+import { isOptionalString } from '@ankhorage/utility/string';
+
 import { type AppNavigatorManifest, NAVIGATOR_PRESETS, NAVIGATOR_TYPES } from '../navigator';
 import { isIconSpec } from './icon';
 import {
-  hasOnlyKeys,
   isDrawerNavigatorOptions,
   isNavigatorScreenReference,
   isStackImplementationConfig,
   isStackScreenOptions,
   isTabsImplementationConfig,
 } from './navigatorOptions';
-import { isOptionalBoolean, isOptionalString, isRecord, isStringArray } from './shared';
 
 /*** Validate the complete serialized `AppManifest.navigator` slice. */
 export function isAppNavigatorManifest(value: unknown): value is AppNavigatorManifest {
@@ -72,12 +74,11 @@ function isRouteDefinition(value: unknown): boolean {
   return (
     isRecord(value) &&
     typeof value.name === 'string' &&
-    isOptionalString(value.path) &&
-    isOptionalString(value.label) &&
+    [value.path, value.label, value.screenId].every(isOptionalString) &&
     (value.icon === undefined || isIconSpec(value.icon)) &&
-    isOptionalBoolean(value.showInPrimaryNavigation) &&
+    (value.showInPrimaryNavigation === undefined ||
+      typeof value.showInPrimaryNavigation === 'boolean') &&
     (value.guards === undefined || isStringArray(value.guards)) &&
-    isOptionalString(value.screenId) &&
     (value.stackOptions === undefined || isStackScreenOptions(value.stackOptions)) &&
     (value.navigator === undefined || isNavigatorNode(value.navigator))
   );

package/src/appManifest/navigatorOptions.ts

@@ -1,3 +1,6 @@
+import { hasOnlyKeys, isRecord } from '@ankhorage/utility/object';
+import { isOptionalString } from '@ankhorage/utility/string';
+
 import {
   DRAWER_POSITIONS,
   DRAWER_TYPES,
@@ -8,7 +11,6 @@ import {
   NATIVE_TABS_MINIMIZE_BEHAVIORS,
   STACK_PRESENTATIONS,
 } from '../navigator';
-import { isOptionalBoolean, isOptionalString, isRecord } from './shared';
 
 /*** Validate stable native, JavaScript, or alpha Experimental Stack desired state. */
 export function isStackImplementationConfig(value: Record<string, unknown>): boolean {
@@ -63,7 +65,7 @@ export function isStackScreenOptions(value: unknown): boolean {
   }
   return (
     (value.sheetAllowedDetents === undefined || isSheetAllowedDetents(value.sheetAllowedDetents)) &&
-    isOptionalBoolean(value.sheetGrabberVisible)
+    (value.sheetGrabberVisible === undefined || typeof value.sheetGrabberVisible === 'boolean')
   );
 }
 
@@ -77,8 +79,8 @@ export function isDrawerNavigatorOptions(value: unknown): boolean {
         contains(DRAWER_POSITIONS, value.drawerPosition))) &&
     (value.drawerType === undefined ||
       (typeof value.drawerType === 'string' && contains(DRAWER_TYPES, value.drawerType))) &&
-    isOptionalBoolean(value.swipeEnabled) &&
-    isOptionalBoolean(value.headerShown)
+    (value.swipeEnabled === undefined || typeof value.swipeEnabled === 'boolean') &&
+    (value.headerShown === undefined || typeof value.headerShown === 'boolean')
   );
 }
 
@@ -101,15 +103,6 @@ export function isNavigatorScreenReference(value: unknown): boolean {
   return isRecord(value) && hasOnlyKeys(value, ['screenId']) && typeof value.screenId === 'string';
 }
 
-/*** Check that a finite configuration object contains no unsupported keys. */
-export function hasOnlyKeys(
-  value: Record<string, unknown>,
-  allowedKeys: readonly string[],
-): boolean {
-  const allowed = new Set(allowedKeys);
-  return Object.keys(value).every((key) => allowed.has(key));
-}
-
 /*** Validate JavaScript Stack options without accepting native-only presentations. */
 function isJavaScriptStackScreenOptions(value: unknown): boolean {
   return (
@@ -141,9 +134,9 @@ function isStackHeaderOptions(value: unknown): boolean {
 function isStackHeaderOptionsShape(value: Record<string, unknown>): boolean {
   return (
     isOptionalString(value.title) &&
-    isOptionalBoolean(value.headerShown) &&
-    isOptionalBoolean(value.headerTransparent) &&
-    isOptionalBoolean(value.headerBackVisible)
+    (value.headerShown === undefined || typeof value.headerShown === 'boolean') &&
+    (value.headerTransparent === undefined || typeof value.headerTransparent === 'boolean') &&
+    (value.headerBackVisible === undefined || typeof value.headerBackVisible === 'boolean')
   );
 }
 

package/src/appManifest/parseAppManifest.ts

@@ -0,0 +1,15 @@
+import type { AppManifestParseResult } from '../types/appManifest';
+import { isAppManifest } from './isAppManifest';
+
+/**
+ * Parse unknown JSON-compatible input at the canonical AppManifest boundary.
+ *
+ * Contracts owns structural manifest validation. Consumers may add semantic
+ * diagnostics after this parser succeeds, but should not reconstruct the
+ * AppManifest shape in their own packages.
+ */
+export function parseAppManifest(value: unknown): AppManifestParseResult {
+  return isAppManifest(value)
+    ? { ok: true, manifest: value }
+    : { ok: false, message: 'Value is not a canonical AppManifest.' };
+}

package/src/appManifest/screens.ts

@@ -1,9 +1,10 @@
 import { COLOR_HARMONIES } from '@ankhorage/color-theory';
+import { isRecord } from '@ankhorage/utility/object';
+import { isOptionalString } from '@ankhorage/utility/string';
 
 import { isMediaAssetReference } from '../media';
 import { APP_CATEGORIES } from '../types';
 import { isBindingValueSource, isScreenDataLoaderDefinition } from './bindings';
-import { isOptionalNumber, isOptionalString, isRecord } from './shared';
 
 export { isAppNavigatorManifest } from './navigator';
 
@@ -11,6 +12,7 @@ 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']);
 
+/*** Validate application identity and optional authored metadata. */
 export function isManifestMetadata(value: unknown): boolean {
   return (
     isRecord(value) &&
@@ -25,6 +27,7 @@ export function isManifestMetadata(value: unknown): boolean {
   );
 }
 
+/*** Validate theme identity and its required light and dark modes. */
 export function isThemeConfig(value: unknown): boolean {
   return (
     isRecord(value) &&
@@ -35,6 +38,7 @@ export function isThemeConfig(value: unknown): boolean {
   );
 }
 
+/*** Validate screens in the authored screen registry. */
 export function isScreenRegistry(value: unknown): boolean {
   return (
     isRecord(value) &&
@@ -45,6 +49,7 @@ export function isScreenRegistry(value: unknown): boolean {
   );
 }
 
+/*** Validate optional light and dark splash-screen configuration. */
 export function isSplashScreenSpec(value: unknown): boolean {
   return (
     isSplashScreenModeSpec(value) &&
@@ -53,6 +58,7 @@ export function isSplashScreenSpec(value: unknown): boolean {
   );
 }
 
+/*** Validate the primary color and supported color harmony of a theme mode. */
 function isThemeModeConfig(value: unknown): boolean {
   return (
     isRecord(value) &&
@@ -62,6 +68,7 @@ function isThemeModeConfig(value: unknown): boolean {
   );
 }
 
+/*** Validate an authored component node and its nested children. */
 function isUiNode(value: unknown): boolean {
   return (
     isRecord(value) &&
@@ -76,6 +83,7 @@ function isUiNode(value: unknown): boolean {
   );
 }
 
+/*** Validate repeat source and item binding configuration. */
 function isUiNodeRepeatSpec(value: unknown): boolean {
   return (
     isRecord(value) &&
@@ -86,6 +94,7 @@ function isUiNodeRepeatSpec(value: unknown): boolean {
   );
 }
 
+/*** Validate screen identity, root component and optional requirements. */
 function isScreenSpec(value: unknown): boolean {
   return (
     isRecord(value) &&
@@ -101,11 +110,12 @@ function isScreenSpec(value: unknown): boolean {
   );
 }
 
+/*** Validate one splash-screen appearance configuration. */
 function isSplashScreenModeSpec(value: unknown): boolean {
   return (
     isRecord(value) &&
     (value.image === undefined || isMediaAssetReference(value.image)) &&
-    isOptionalNumber(value.imageWidth) &&
+    (value.imageWidth === undefined || typeof value.imageWidth === 'number') &&
     (value.resizeMode === undefined ||
       (typeof value.resizeMode === 'string' &&
         SPLASH_SCREEN_RESIZE_MODE_SET.has(value.resizeMode))) &&
@@ -113,6 +123,7 @@ function isSplashScreenModeSpec(value: unknown): boolean {
   );
 }
 
+/*** Validate screen capability and permission requirements. */
 function isScreenRequirements(value: unknown): boolean {
   return (
     isRecord(value) &&
@@ -121,6 +132,7 @@ function isScreenRequirements(value: unknown): boolean {
   );
 }
 
+/*** Validate the entries of a capability or permission requirement list. */
 function isRequirementArray(value: unknown, key: 'capability' | 'permission'): boolean {
   return (
     Array.isArray(value) &&

package/src/appManifest/splashScreen.test.ts

@@ -0,0 +1,40 @@
+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', () => {
+    const splashScreen: SplashScreenSpec = {
+      backgroundColor: '#ffffff',
+      image: { mediaId: 'splash-logo' },
+      imageWidth: 160,
+      resizeMode: 'contain',
+      dark: {
+        backgroundColor: '#000000',
+        image: { mediaId: 'splash-logo-dark' },
+      },
+    };
+
+    const manifest: Pick<AppManifest, 'splashScreen'> = { splashScreen };
+
+    expect(JSON.parse(JSON.stringify(manifest))).toEqual({ splashScreen });
+  });
+
+  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.
+        imageWidth: 160,
+      },
+    };
+    const splashWithDarkResizeMode: SplashScreenSpec = {
+      dark: {
+        // @ts-expect-error Expo dark-mode options do not include resize mode.
+        resizeMode: 'contain',
+      },
+    };
+
+    expect(splashWithDarkImageWidth.dark).toEqual({ imageWidth: 160 });
+    expect(splashWithDarkResizeMode.dark).toEqual({ resizeMode: 'contain' });
+  });
+});

package/src/appManifest/splashScreen.ts

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

package/src/appManifest.test.ts

@@ -37,12 +37,16 @@ function createManifest(): Record<string, unknown> {
         },
       },
     },
+    state: { provider: 'legend', persistence: false },
     infra: {
-      deployment: { target: 'minikube', monitoring: true },
-      database: { provider: 'supabase', tier: 'dev' },
-      storage: { provider: 'auto', buckets: ['media'] },
-      state: { provider: 'legend', persistence: 'local' },
-      networking: { domain: 'example.test', cdn: false },
+      environments: {
+        local: {
+          deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
+          database: { provider: 'supabase', tier: 'dev' },
+          objectStorage: { provider: 'supabase', buckets: ['media'] },
+          networking: { domain: 'example.test' },
+        },
+      },
       apis: [
         {
           id: 'nutrition',

package/src/appManifest.ts

@@ -1,106 +1,8 @@
-import { isComponentDataBindingRegistry } from './appManifest/bindings';
-import { isDataSourceRegistry } from './appManifest/dataSources';
-import { isAppDeployManifest } from './appManifest/deploy';
-import { isInfraManifest } from './appManifest/infra';
-import { isMediaManifest } from './appManifest/media';
-import {
-  isAppNavigatorManifest,
-  isManifestMetadata,
-  isScreenRegistry,
-  isSplashScreenSpec,
-  isThemeConfig,
-} from './appManifest/screens';
-import { isRecord, isStringArray } from './appManifest/shared';
-import type { AppManifest } from './types';
-
-export type AppManifestParseResult =
-  | { readonly ok: true; readonly manifest: AppManifest }
-  | { readonly ok: false; readonly message: string };
-
-const APP_MANIFEST_KEY_POLICY = {
-  metadata: 'required',
-  themes: 'required',
-  activeThemeId: 'required',
-  activeThemeMode: 'optional',
-  splashScreen: 'optional',
-  media: 'optional',
-  deploy: 'optional',
-  infra: 'required',
-  navigator: 'required',
-  screens: 'required',
-  dataSources: 'optional',
-  dataBindings: 'optional',
-  repository: 'optional',
-  settings: 'required',
-} as const satisfies Record<keyof AppManifest, 'optional' | 'required'>;
-
-/**
- * Parse unknown JSON-compatible input at the canonical AppManifest boundary.
- *
- * Contracts owns structural manifest validation. Consumers may add semantic
- * diagnostics after this parser succeeds, but should not reconstruct the
- * AppManifest shape in their own packages.
- */
-export function parseAppManifest(value: unknown): AppManifestParseResult {
-  return isAppManifest(value)
-    ? { ok: true, manifest: value }
-    : { ok: false, message: 'Value is not a canonical AppManifest.' };
-}
-
-/** Return whether an unknown value satisfies the canonical AppManifest shape. */
-export function isAppManifest(value: unknown): value is AppManifest {
-  return (
-    isRecord(value) &&
-    hasRequiredManifestKeys(value) &&
-    !('generatedApis' in value) &&
-    isManifestMetadata(value.metadata) &&
-    Array.isArray(value.themes) &&
-    value.themes.every(isThemeConfig) &&
-    typeof value.activeThemeId === 'string' &&
-    isActiveThemeMode(value.activeThemeMode) &&
-    (value.splashScreen === undefined || isSplashScreenSpec(value.splashScreen)) &&
-    (value.media === undefined || isMediaManifest(value.media)) &&
-    (value.deploy === undefined || isAppDeployManifest(value.deploy)) &&
-    isInfraManifest(value.infra) &&
-    isAppNavigatorManifest(value.navigator) &&
-    isScreenRegistry(value.screens) &&
-    (value.dataSources === undefined || isDataSourceRegistry(value.dataSources)) &&
-    (value.dataBindings === undefined || isComponentDataBindingRegistry(value.dataBindings)) &&
-    (value.repository === undefined || isRepositoryManifest(value.repository)) &&
-    isAppSettings(value.settings)
-  );
-}
-
-function hasRequiredManifestKeys(value: Record<string, unknown>): boolean {
-  return Object.entries(APP_MANIFEST_KEY_POLICY).every(
-    ([key, policy]) => policy === 'optional' || key in value,
-  );
-}
-
-function isActiveThemeMode(value: unknown): boolean {
-  return value === undefined || value === 'dark' || value === 'light';
-}
-
-function isRepositoryManifest(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    value.provider === 'github' &&
-    typeof value.owner === 'string' &&
-    value.owner.length > 0 &&
-    typeof value.name === 'string' &&
-    value.name.length > 0 &&
-    typeof value.url === 'string' &&
-    value.url.length > 0 &&
-    value.defaultBranch === 'main'
-  );
-}
-
-function isAppSettings(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    !('apiBaseUrl' in value) &&
-    isRecord(value.localization) &&
-    typeof value.localization.defaultLocale === 'string' &&
-    isStringArray(value.localization.locales)
-  );
-}
+export { isAppManifest } from './appManifest/isAppManifest';
+export { parseAppManifest } from './appManifest/parseAppManifest';
+export type {
+  SplashScreenModeSpec,
+  SplashScreenResizeMode,
+  SplashScreenSpec,
+} from './appManifest/splashScreen';
+export type { AppManifestParseResult } from './types/appManifest';

package/src/auth-flow-contract.test.ts

@@ -7,8 +7,8 @@ import {
   type AppSettings,
   type AuthFlowConfig,
   type AuthProviderConfig,
-  type AuthSpec,
   DEFAULT_AUTH_FLOW,
+  type InfraAuthSpec,
   resolveAuthFlow,
 } from './index';
 
@@ -52,13 +52,13 @@ describe('canonical authentication flow contract', () => {
   });
 
   it('allows authentication without an authorization model', () => {
-    const auth: AuthSpec = {
+    const auth: InfraAuthSpec = {
       scope: 'global',
       provider: 'supabase',
       flow: DEFAULT_AUTH_FLOW,
     };
 
-    expect(auth.authorization).toBeUndefined();
+    expect(Object.hasOwn(auth, 'authorization')).toBe(false);
   });
 
   it('removes auth flow from application settings at compile time', () => {
@@ -91,13 +91,9 @@ describe('canonical authentication flow contract', () => {
     expect(removedProperty.provider).toBe('supabase');
   });
 
-  it('makes authorization access require explicit narrowing', () => {
-    const assumesAuthorization = (auth: AuthSpec): string => {
-      // @ts-expect-error Authorization is optional and must be checked before use.
-      return auth.authorization.kind;
-    };
-
-    expect(typeof assumesAuthorization).toBe('function');
+  it('removes nested authorization from the authentication contract', () => {
+    const hasAuthorization: 'authorization' extends keyof InfraAuthSpec ? true : false = false;
+    expect(hasAuthorization).toBe(false);
   });
 
   it('prevents the removed settings auth-flow path from returning to source', async () => {

package/src/auth-oauth.test.ts

@@ -11,7 +11,7 @@ import {
   type AuthAdapter,
   type AuthOAuthConfig,
   type AuthSession,
-  type AuthSpec,
+  type InfraAuthSpec,
 } from './index';
 
 const session: AuthSession = {
@@ -80,7 +80,7 @@ describe('OAuth auth contracts', () => {
       ],
     };
 
-    const auth: AuthSpec = {
+    const auth: InfraAuthSpec = {
       scope: 'global',
       provider: 'supabase',
       oauth,

package/src/auth.ts

@@ -1,4 +1,5 @@
-import type { AppDeployEnvironmentId, AppDeployTargetId } from './deploy';
+import type { AppDeployTargetId } from './deploy';
+import type { AppEnvironmentId } from './environments';
 import type { SecretRef } from './secrets';
 import type { IconSpec } from './types';
 
@@ -90,7 +91,7 @@ export type AuthOAuthSetupRequirement =
 export interface AuthOAuthSetupPlan {
   readonly provider: AuthOAuthProviderId;
   readonly transport: AuthOAuthTransportId;
-  readonly environment: AppDeployEnvironmentId;
+  readonly environment: AppEnvironmentId;
   /** Enabled application targets considered while deriving this plan. */
   readonly targets: readonly AppDeployTargetId[];
   readonly requirements: readonly AuthOAuthSetupRequirement[];

package/src/bindings.test.ts

@@ -490,6 +490,11 @@ describe('component data-binding contracts', () => {
       ],
       activeThemeId: 'default',
       infra: {
+        environments: {
+          local: {
+            deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
+          },
+        },
         apis: [
           {
             id: 'cms',