@endo/compartment-mapper 1.6.3 → 2.1.0

package/src/compartment-map.js

@@ -1,14 +1,43 @@
 /* Validates a compartment map against its schema. */
 
-import { assertPackagePolicy } from './policy-format.js';
+import {
+  assertPackagePolicy,
+  ATTENUATORS_COMPARTMENT,
+  ENTRY_COMPARTMENT,
+} from './policy-format.js';
 
-/** @import {CompartmentMapDescriptor} from './types.js' */
+/**
+ * @import {
+ *   FileCompartmentDescriptor,
+ *   FileCompartmentMapDescriptor,
+ *   FileModuleConfiguration,
+ *   CompartmentMapDescriptor,
+ *   EntryDescriptor,
+ *   ModuleConfiguration,
+ *   ExitModuleConfiguration,
+ *   CompartmentModuleConfiguration,
+ *   CompartmentDescriptor,
+ *   ScopeDescriptor,
+ *   BaseModuleConfiguration,
+ *   DigestedCompartmentMapDescriptor,
+ *   PackageCompartmentMapDescriptor,
+ *   PackageCompartmentDescriptor,
+ *   FileUrlString,
+ *   LanguageForExtension,
+ *   LanguageForModuleSpecifier,
+ *   ModuleConfigurationKind,
+ *   ModuleConfigurationKindToType,
+ *   ErrorModuleConfiguration,
+ *   DigestedCompartmentDescriptor} from './types.js'
+ */
 
 // TODO convert to the new `||` assert style.
 // Deferred because this file pervasively uses simple template strings rather than
 // template strings tagged with `assert.details` (aka `X`), and uses
 // this definition of `q` rather than `assert.quote`
 const q = JSON.stringify;
+const { keys, entries } = Object;
+const { isArray } = Array;
 
 /** @type {(a: string, b: string) => number} */
 // eslint-disable-next-line no-nested-ternary
@@ -26,432 +55,887 @@ function* enumerate(iterable) {
   }
 }
 
+/**
+ * Type guard for a string value.
+ *
+ * @overload
+ * @param {unknown} value
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts value is string}
+ */
+
+/**
+ * Type guard for a string value with a custom assertion failure message.
+ *
+ * @overload
+ * @param {unknown} value
+ * @param {string} message
+ * @returns {asserts value is string}
+ */
+
+/**
+ * Type guard for a string value.
+ *
+ * @param {unknown} value
+ * @param {string} pathOrMessage
+ * @param {string} url
+ * @returns {asserts value is string}
+ */
+const assertString = (value, pathOrMessage, url) => {
+  const keypath = pathOrMessage;
+  assert.typeof(
+    value,
+    'string',
+    `${keypath} in ${q(url)} must be a string; got ${q(value)}`,
+  );
+};
+
+/**
+ * Asserts the `label` field valid
+ *
+ * @param {unknown} allegedLabel
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts alleged is string}
+ */
+const assertLabel = (allegedLabel, keypath, url) => {
+  assertString(allegedLabel, keypath, url);
+  if (allegedLabel === ATTENUATORS_COMPARTMENT) {
+    return;
+  }
+  if (allegedLabel === ENTRY_COMPARTMENT) {
+    return;
+  }
+  assert(
+    /^(?:@[a-z][a-z0-9-.]*\/)?[a-z][a-z0-9-.]*(?:>(?:@[a-z][a-z0-9-.]*\/)?[a-z][a-z0-9-.]*)*$/.test(
+      allegedLabel,
+    ),
+    `${keypath} must be a canonical name in ${q(url)}; got ${q(allegedLabel)}`,
+  );
+};
+
+/**
+ * @param {unknown} allegedObject
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts allegedObject is Record<PropertyKey, unknown>}
+ */
+const assertPlainObject = (allegedObject, keypath, url) => {
+  const object = Object(allegedObject);
+  assert(
+    object === allegedObject &&
+      !isArray(object) &&
+      !(typeof object === 'function'),
+    `${keypath} must be an object; got ${q(allegedObject)} of type ${q(typeof allegedObject)} in ${q(url)}`,
+  );
+};
+
+/**
+ *
+ * @param {unknown} value
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts value is boolean}
+ */
+const assertBoolean = (value, keypath, url) => {
+  assert.typeof(
+    value,
+    'boolean',
+    `${keypath} in ${q(url)} must be a boolean; got ${q(value)}`,
+  );
+};
+
 /**
  * @param {Record<string, unknown>} object
  * @param {string} message
  */
 const assertEmptyObject = (object, message) => {
-  assert(Object.keys(object).length === 0, message);
+  assert(keys(object).length === 0, message);
 };
 
 /**
  * @param {unknown} conditions
  * @param {string} url
+ * @returns {asserts conditions is CompartmentMapDescriptor['tags']}
  */
 const assertConditions = (conditions, url) => {
   if (conditions === undefined) return;
   assert(
-    Array.isArray(conditions),
-    `conditions must be an array, got ${conditions} in ${q(url)}`,
+    isArray(conditions),
+    `conditions must be an array; got ${conditions} in ${q(url)}`,
   );
   for (const [index, value] of enumerate(conditions)) {
-    assert.typeof(
-      value,
-      'string',
-      `conditions[${index}] must be a string, got ${value} in ${q(url)}`,
-    );
+    assertString(value, `conditions[${index}]`, url);
   }
 };
 
 /**
- * @param {Record<string, unknown>} allegedModule
- * @param {string} path
+ * @template {Partial<ModuleConfiguration>} T
+ * @param {T} allegedModule
+ * @returns {Omit<T, keyof BaseModuleConfiguration>}
+ */
+const getModuleConfigurationSpecificProperties = allegedModule => {
+  const {
+    retained: _retained,
+    deferredError: _deferredError,
+    ...other
+  } = allegedModule;
+  return /** @type {Omit<T, keyof BaseModuleConfiguration>} */ (
+    Object.fromEntries(entries(other).filter(([key]) => !key.startsWith('_')))
+  );
+};
+
+/**
+ *
+ * @param {Record<PropertyKey, unknown>} allegedModule
+ * @param {string} keypath
  * @param {string} url
+ * @returns {asserts allegedModule is ModuleConfiguration}
  */
-const assertCompartmentModule = (allegedModule, path, url) => {
-  const { compartment, module, retained, ...extra } = allegedModule;
+const assertBaseModuleConfiguration = (allegedModule, keypath, url) => {
+  const { deferredError, retained, createdBy } = allegedModule;
+  if (deferredError !== undefined) {
+    assertString(deferredError, `${keypath}.deferredError`, url);
+  }
+  if (retained !== undefined) {
+    assertBoolean(retained, `${keypath}.retained`, url);
+  }
+  if (createdBy !== undefined) {
+    assertString(createdBy, `${keypath}.createdBy`, url);
+  }
+};
+
+/**
+ * @param {ModuleConfiguration} moduleDescriptor
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts allegedModule is CompartmentModuleConfiguration}
+ */
+const assertCompartmentModuleConfiguration = (
+  moduleDescriptor,
+  keypath,
+  url,
+) => {
+  const { compartment, module, ...extra } =
+    getModuleConfigurationSpecificProperties(
+      /** @type {CompartmentModuleConfiguration} */ (moduleDescriptor),
+    );
   assertEmptyObject(
     extra,
-    `${path} must not have extra properties, got ${q({
-      extra,
-      compartment,
-    })} in ${q(url)}`,
+    `${keypath} must not have extra properties; got ${q(extra)} in ${q(url)}`,
   );
-  assert.typeof(
-    compartment,
-    'string',
-    `${path}.compartment must be a string, got ${q(compartment)} in ${q(url)}`,
-  );
-  assert.typeof(
-    module,
-    'string',
-    `${path}.module must be a string, got ${q(module)} in ${q(url)}`,
-  );
-  if (retained !== undefined) {
-    assert.typeof(
-      retained,
-      'boolean',
-      `${path}.retained must be a boolean, got ${q(retained)} in ${q(url)}`,
-    );
-  }
+
+  assertString(compartment, `${keypath}.compartment`, url);
+  assertString(module, `${keypath}.module`, url);
 };
 
 /**
- * @param {Record<string, unknown>} allegedModule
- * @param {string} path
+ * @param {ModuleConfiguration} moduleDescriptor
+ * @param {string} keypath
  * @param {string} url
+ * @returns {asserts allegedModule is FileModuleConfiguration}
  */
-const assertFileModule = (allegedModule, path, url) => {
-  const { location, parser, sha512, ...extra } = allegedModule;
+const assertFileModuleConfiguration = (moduleDescriptor, keypath, url) => {
+  const { location, parser, sha512, ...extra } =
+    getModuleConfigurationSpecificProperties(
+      /** @type {FileModuleConfiguration} */ (moduleDescriptor),
+    );
   assertEmptyObject(
     extra,
-    `${path} must not have extra properties, got ${q(
-      Object.keys(extra),
+    `${keypath} must not have extra properties; got ${q(
+      keys(extra),
     )} in ${q(url)}`,
   );
-  assert.typeof(
-    location,
-    'string',
-    `${path}.location must be a string, got ${q(location)} in ${q(url)}`,
-  );
-  assert.typeof(
-    parser,
-    'string',
-    `${path}.parser must be a string, got ${q(parser)} in ${q(url)}`,
-  );
+  if (location !== undefined) {
+    assertString(location, `${keypath}.location`, url);
+  }
+  assertString(parser, `${keypath}.parser`, url);
 
   if (sha512 !== undefined) {
-    assert.typeof(
-      sha512,
-      'string',
-      `${path}.sha512 must be a string, got ${q(sha512)} in ${q(url)}`,
-    );
+    assertString(sha512, `${keypath}.sha512`, url);
   }
 };
 
 /**
- * @param {Record<string, unknown>} allegedModule
- * @param {string} path
+ * @param {ModuleConfiguration} moduleDescriptor
+ * @param {string} keypath
  * @param {string} url
+ * @returns {asserts allegedModule is ExitModuleConfiguration}
  */
-const assertExitModule = (allegedModule, path, url) => {
-  const { exit, ...extra } = allegedModule;
+const assertExitModuleConfiguration = (moduleDescriptor, keypath, url) => {
+  const { exit, ...extra } = getModuleConfigurationSpecificProperties(
+    /** @type {ExitModuleConfiguration} */ (moduleDescriptor),
+  );
   assertEmptyObject(
     extra,
-    `${path} must not have extra properties, got ${q(
-      Object.keys(extra),
+    `${keypath} must not have extra properties; got ${q(
+      keys(extra),
     )} in ${q(url)}`,
   );
-  assert.typeof(
-    exit,
-    'string',
-    `${path}.exit must be a string, got ${q(exit)} in ${q(url)}`,
-  );
+  assertString(exit, `${keypath}.exit`, url);
 };
 
 /**
+ *
+ * @param {ModuleConfiguration} moduleDescriptor
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts moduleDescriptor is ErrorModuleConfiguration}
+ */
+const assertErrorModuleConfiguration = (moduleDescriptor, keypath, url) => {
+  const { deferredError } = moduleDescriptor;
+  if (deferredError) {
+    assertString(deferredError, `${keypath}.deferredError`, url);
+  }
+};
+
+/**
+ * @template {ModuleConfigurationKind[]} Kinds
+ * @overload
  * @param {unknown} allegedModule
- * @param {string} path
+ * @param {string} keypath
  * @param {string} url
+ * @param {Kinds} kinds
+ * @returns {asserts allegedModule is ModuleConfigurationKindToType<Kinds>}
  */
-const assertModule = (allegedModule, path, url) => {
-  const moduleDescriptor = Object(allegedModule);
+
+/**
+ * @overload
+ * @param {unknown} allegedModule
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts allegedModule is ModuleConfiguration}
+ */
+
+/**
+ * @param {unknown} allegedModule
+ * @param {string} keypath
+ * @param {string} url
+ * @param {ModuleConfigurationKind[]} kinds
+ */
+function assertModuleConfiguration(allegedModule, keypath, url, kinds) {
+  assertPlainObject(allegedModule, keypath, url);
+  assertBaseModuleConfiguration(allegedModule, keypath, url);
+
+  const finalKinds =
+    kinds.length > 0
+      ? kinds
+      : /** @type {ModuleConfigurationKind[]} */ ([
+          'compartment',
+          'file',
+          'exit',
+          'error',
+        ]);
+  /** @type {Error[]} */
+  const errors = [];
+  for (const kind of finalKinds) {
+    switch (kind) {
+      case 'compartment': {
+        try {
+          assertCompartmentModuleConfiguration(allegedModule, keypath, url);
+        } catch (error) {
+          errors.push(error);
+        }
+        break;
+      }
+      case 'file': {
+        try {
+          assertFileModuleConfiguration(allegedModule, keypath, url);
+        } catch (error) {
+          errors.push(error);
+        }
+        break;
+      }
+      case 'exit': {
+        try {
+          assertExitModuleConfiguration(allegedModule, keypath, url);
+        } catch (error) {
+          errors.push(error);
+        }
+        break;
+      }
+      case 'error': {
+        try {
+          assertErrorModuleConfiguration(allegedModule, keypath, url);
+        } catch (error) {
+          errors.push(error);
+        }
+        break;
+      }
+      default:
+        throw new TypeError(
+          `Unknown module descriptor kind ${q(kind)} in ${q(url)}`,
+        );
+    }
+  }
+
   assert(
-    allegedModule === moduleDescriptor && !Array.isArray(moduleDescriptor),
-    `${path} must be an object, got ${allegedModule} in ${q(url)}`,
+    errors.length < finalKinds.length,
+    `invalid module descriptor in ${q(url)} at ${q(keypath)}; expected to match one of ${q(kinds)}: ${errors.map(err => err.message).join('; ')}`,
   );
+}
 
-  const { compartment, module, location, parser, exit, deferredError } =
-    moduleDescriptor;
-  if (compartment !== undefined || module !== undefined) {
-    assertCompartmentModule(moduleDescriptor, path, url);
-  } else if (location !== undefined || parser !== undefined) {
-    assertFileModule(moduleDescriptor, path, url);
-  } else if (exit !== undefined) {
-    assertExitModule(moduleDescriptor, path, url);
-  } else if (deferredError !== undefined) {
-    assert.typeof(
-      deferredError,
-      'string',
-      `${path}.deferredError must be a string contaiing an error message`,
+/**
+ * @param {unknown} allegedModules
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts allegedModules is Record<string, ModuleConfiguration>}
+ */
+const assertModuleConfigurations = (allegedModules, keypath, url) => {
+  assertPlainObject(allegedModules, keypath, url);
+  for (const [key, value] of entries(allegedModules)) {
+    assertString(
+      key,
+      `all keys of ${keypath}.modules must be strings; got ${key} in ${q(url)}`,
     );
-  } else {
-    assert.fail(
-      `${path} is not a valid module descriptor, got ${q(allegedModule)} in ${q(
-        url,
-      )}`,
+    assertModuleConfiguration(value, `${keypath}.modules[${q(key)}]`, url);
+  }
+};
+
+/**
+ * @param {unknown} allegedModules
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts allegedModules is Record<string, FileModuleConfiguration|CompartmentModuleConfiguration>}
+ */
+const assertFileModuleConfigurations = (allegedModules, keypath, url) => {
+  assertPlainObject(allegedModules, keypath, url);
+  for (const [key, value] of entries(allegedModules)) {
+    assertString(
+      key,
+      `all keys of ${keypath}.modules must be strings; got ${key} in ${q(url)}`,
     );
+    assertModuleConfiguration(value, `${keypath}.modules[${q(key)}]`, url, [
+      'file',
+      'compartment',
+      'error',
+    ]);
   }
 };
 
 /**
  * @param {unknown} allegedModules
- * @param {string} path
+ * @param {string} keypath
  * @param {string} url
+ * @returns {asserts allegedModules is Record<string, ModuleConfiguration>}
  */
-const assertModules = (allegedModules, path, url) => {
-  const modules = Object(allegedModules);
-  assert(
-    allegedModules === modules || !Array.isArray(modules),
-    `modules must be an object, got ${q(allegedModules)} in ${q(url)}`,
-  );
-  for (const [key, value] of Object.entries(modules)) {
-    assertModule(value, `${path}.modules[${q(key)}]`, url);
+const assertDigestedModuleConfigurations = (allegedModules, keypath, url) => {
+  assertPlainObject(allegedModules, keypath, url);
+  for (const [key, value] of entries(allegedModules)) {
+    assertString(
+      key,
+      `all keys of ${keypath}.modules must be strings; got ${key} in ${q(url)}`,
+    );
+    assertModuleConfiguration(value, `${keypath}.modules[${q(key)}]`, url, [
+      'file',
+      'exit',
+      'error',
+    ]);
   }
 };
 
 /**
  * @param {unknown} allegedParsers
- * @param {string} path
+ * @param {string} keypath
  * @param {string} url
+ * @returns {asserts allegedParsers is LanguageForExtension}
  */
-const assertParsers = (allegedParsers, path, url) => {
-  if (allegedParsers === undefined) {
-    return;
-  }
-  const parsers = Object(allegedParsers);
-  assert(
-    allegedParsers === parsers && !Array.isArray(parsers),
-    `${path}.parsers must be an object, got ${allegedParsers} in ${q(url)}`,
-  );
+const assertParsers = (allegedParsers, keypath, url) => {
+  assertPlainObject(allegedParsers, `${keypath}.parsers`, url);
 
-  for (const [key, value] of Object.entries(parsers)) {
-    assert.typeof(
+  for (const [key, value] of entries(allegedParsers)) {
+    assertString(
       key,
-      'string',
-      `all keys of ${path}.parsers must be strings, got ${key} in ${q(url)}`,
-    );
-    assert.typeof(
-      value,
-      'string',
-      `${path}.parsers[${q(key)}] must be a string, got ${value} in ${q(url)}`,
+      `all keys of ${keypath}.parsers must be strings; got ${key} in ${q(url)}`,
     );
+    assertString(value, `${keypath}.parsers[${q(key)}]`, url);
   }
 };
 
 /**
- * @param {unknown} allegedScope
- * @param {string} path
+ * @overload
+ * @param {unknown} allegedTruthyValue
+ * @param {string} keypath
  * @param {string} url
+ * @returns {asserts allegedTruthyValue is NonNullable<unknown>}
  */
-const assertScope = (allegedScope, path, url) => {
-  const scope = Object(allegedScope);
+
+/**
+ *
+ * @overload
+ * @param {unknown} allegedTruthyValue
+ * @param {string} message
+ * @returns {asserts allegedTruthyValue is NonNullable<unknown>}
+ */
+
+/**
+ *
+ * @param {unknown} allegedTruthyValue
+ * @param {string} keypath
+ * @param {string} [url]
+ * @returns {asserts allegedTruthyValue is NonNullable<unknown>}
+ */
+const assertTruthy = (allegedTruthyValue, keypath, url) => {
   assert(
-    allegedScope === scope && !Array.isArray(scope),
-    `${path} must be an object, got ${allegedScope} in ${q(url)}`,
+    allegedTruthyValue,
+    url
+      ? `${keypath} in ${q(url)} must be truthy; got ${q(allegedTruthyValue)}`
+      : url,
   );
+};
+
+/**
+ * @template [T=string]
+ * @typedef {(value: unknown, keypath: string, url: string) => void} AssertFn
+ */
 
-  const { compartment, ...extra } = scope;
+/**
+ * @template [T=string]
+ * @param {unknown} allegedScope
+ * @param {string} keypath
+ * @param {string} url
+ * @param {AssertFn<T>} [assertCompartmentValue]
+ * @returns {asserts allegedScope is ScopeDescriptor<T>}
+ */
+const assertScope = (allegedScope, keypath, url, assertCompartmentValue) => {
+  assertPlainObject(allegedScope, keypath, url);
+
+  const { compartment, ...extra } = allegedScope;
   assertEmptyObject(
     extra,
-    `${path} must not have extra properties, got ${q(
-      Object.keys(extra),
+    `${keypath} must not have extra properties; got ${q(
+      keys(extra),
     )} in ${q(url)}`,
   );
 
-  assert.typeof(
-    compartment,
-    'string',
-    `${path}.compartment must be a string, got ${q(compartment)} in ${q(url)}`,
-  );
+  if (assertCompartmentValue) {
+    assertCompartmentValue(compartment, `${keypath}.compartment`, url);
+  } else {
+    assertString(compartment, `${keypath}.compartment`, url);
+  }
 };
 
 /**
+ * @template [T=string]
  * @param {unknown} allegedScopes
- * @param {string} path
+ * @param {string} keypath
  * @param {string} url
+ * @param {AssertFn<T>} [assertCompartmentValue]
+ * @returns {asserts allegedScopes is Record<string, ScopeDescriptor<T>>}
  */
-const assertScopes = (allegedScopes, path, url) => {
-  if (allegedScopes === undefined) {
-    return;
-  }
-  const scopes = Object(allegedScopes);
-  assert(
-    allegedScopes === scopes && !Array.isArray(scopes),
-    `${path}.scopes must be an object, got ${q(allegedScopes)} in ${q(url)}`,
-  );
+const assertScopes = (
+  allegedScopes,
+  keypath,
+  url,
+  assertCompartmentValue = assertString,
+) => {
+  assertPlainObject(allegedScopes, keypath, url);
 
-  for (const [key, value] of Object.entries(scopes)) {
-    assert.typeof(
+  for (const [key, value] of entries(allegedScopes)) {
+    assertString(
       key,
-      'string',
-      `all keys of ${path}.scopes must be strings, got ${key} in ${q(url)}`,
+      `all keys of ${keypath}.scopes must be strings; got ${key} in ${q(url)}`,
+    );
+    assertScope(
+      value,
+      `${keypath}.scopes[${q(key)}]`,
+      url,
+      assertCompartmentValue,
     );
-    assertScope(value, `${path}.scopes[${q(key)}]`, url);
   }
 };
 
 /**
  * @param {unknown} allegedTypes
- * @param {string} path
+ * @param {string} keypath
  * @param {string} url
+ * @returns {asserts allegedTypes is LanguageForModuleSpecifier}
  */
-const assertTypes = (allegedTypes, path, url) => {
-  if (allegedTypes === undefined) {
-    return;
+const assertTypes = (allegedTypes, keypath, url) => {
+  assertPlainObject(allegedTypes, `${keypath}.types`, url);
+
+  for (const [key, value] of entries(allegedTypes)) {
+    assertString(
+      key,
+      `all keys of ${keypath}.types must be strings; got ${key} in ${q(url)}`,
+    );
+    assertString(value, `${keypath}.types[${q(key)}]`, url);
+  }
+};
+
+/**
+ * @template {Record<string, ModuleConfiguration>} [M=Record<string, ModuleConfiguration>]
+ * @param {unknown} allegedCompartment
+ * @param {string} keypath
+ * @param {string} url
+ * @param {AssertFn<M>} [moduleConfigurationAssertionFn]
+ * @returns {asserts allegedCompartment is CompartmentDescriptor}
+ */
+const assertCompartmentDescriptor = (
+  allegedCompartment,
+  keypath,
+  url,
+  moduleConfigurationAssertionFn = assertModuleConfigurations,
+) => {
+  assertPlainObject(allegedCompartment, keypath, url);
+
+  const {
+    location,
+    name,
+    parsers,
+    types,
+    scopes,
+    modules,
+    policy,
+    sourceDirname,
+    retained,
+  } = allegedCompartment;
+
+  assertString(location, `${keypath}.location`, url);
+  assertString(name, `${keypath}.name`, url);
+
+  // TODO: It may be prudent to assert that there exists some module referring
+  // to its own compartment
+
+  moduleConfigurationAssertionFn(modules, keypath, url);
+
+  if (parsers !== undefined) {
+    assertParsers(parsers, keypath, url);
+  }
+  if (scopes !== undefined) {
+    assertScopes(scopes, keypath, url);
+  }
+  if (types !== undefined) {
+    assertTypes(types, keypath, url);
   }
-  const types = Object(allegedTypes);
+  if (policy !== undefined) {
+    assertPackagePolicy(policy, keypath, url);
+  }
+  if (sourceDirname !== undefined) {
+    assertString(sourceDirname, `${keypath}.sourceDirname`, url);
+  }
+  if (retained !== undefined) {
+    assertBoolean(retained, `${keypath}.retained`, url);
+  }
+};
+
+/**
+ * Ensures a string is a file URL (a {@link FileUrlString})
+ *
+ * @param {unknown} allegedFileUrlString - a package location to assert
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts allegedFileUrlString is FileUrlString}
+ */
+const assertFileUrlString = (allegedFileUrlString, keypath, url) => {
+  assertString(allegedFileUrlString, keypath, url);
+  assert(
+    allegedFileUrlString.startsWith('file://'),
+    `${keypath} must be a file URL in ${q(url)}; got ${q(allegedFileUrlString)}`,
+  );
   assert(
-    allegedTypes === types && !Array.isArray(types),
-    `${path}.types must be an object, got ${allegedTypes} in ${q(url)}`,
+    allegedFileUrlString.length > 7,
+    `${keypath} must contain a non-empty path in ${q(url)}; got ${q(allegedFileUrlString)}`,
   );
+};
 
-  for (const [key, value] of Object.entries(types)) {
-    assert.typeof(
+/**
+ * @param {unknown} allegedModules
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts allegedModules is Record<string, CompartmentModuleConfiguration>}
+ */
+const assertPackageModuleConfigurations = (allegedModules, keypath, url) => {
+  assertPlainObject(allegedModules, keypath, url);
+  for (const [key, value] of entries(allegedModules)) {
+    assertString(
       key,
-      'string',
-      `all keys of ${path}.types must be strings, got ${key} in ${q(url)}`,
-    );
-    assert.typeof(
-      value,
-      'string',
-      `${path}.types[${q(key)}] must be a string, got ${value} in ${q(url)}`,
+      `all keys of ${keypath}.modules must be strings; got ${key} in ${q(url)}`,
     );
+    assertModuleConfiguration(value, `${keypath}.modules[${q(key)}]`, url, [
+      'compartment',
+    ]);
   }
 };
 
 /**
- * @param {unknown} allegedPolicy
- * @param {string} path
- * @param {string} [url]
+ *
+ * @param {unknown} allegedLocation
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts allegedLocation is PackageCompartmentDescriptor['location']}
  */
-
-const assertPolicy = (
-  allegedPolicy,
-  path,
-  url = '<unknown-compartment-map.json>',
-) => {
-  assertPackagePolicy(allegedPolicy, `${path}.policy`, url);
+const assertPackageLocation = (allegedLocation, keypath, url) => {
+  if (allegedLocation === ATTENUATORS_COMPARTMENT) {
+    return;
+  }
+  assertFileUrlString(allegedLocation, keypath, url);
 };
 
 /**
  * @param {unknown} allegedCompartment
- * @param {string} path
+ * @param {string} keypath
  * @param {string} url
+ * @returns {asserts allegedCompartment is PackageCompartmentDescriptor}
  */
-const assertCompartment = (allegedCompartment, path, url) => {
-  const compartment = Object(allegedCompartment);
-  assert(
-    allegedCompartment === compartment && !Array.isArray(compartment),
-    `${path} must be an object, got ${allegedCompartment} in ${q(url)}`,
+const assertPackageCompartmentDescriptor = (
+  allegedCompartment,
+  keypath,
+  url,
+) => {
+  assertCompartmentDescriptor(
+    allegedCompartment,
+    keypath,
+    url,
+    assertPackageModuleConfigurations,
   );
 
   const {
     location,
-    name,
-    label,
-    parsers,
-    types,
     scopes,
-    modules,
-    policy,
+    label,
+    // these unused vars already validated by assertPackageModuleConfigurations
+    name: _name,
+    sourceDirname: _sourceDirname,
+    modules: _modules,
+    parsers: _parsers,
+    types: _types,
+    policy: _policy,
+    version: _version,
     ...extra
-  } = compartment;
+  } = /** @type {PackageCompartmentDescriptor} */ (allegedCompartment);
 
   assertEmptyObject(
     extra,
-    `${path} must not have extra properties, got ${q(
-      Object.keys(extra),
+    `${keypath} must not have extra properties; got ${q(
+      keys(extra),
     )} in ${q(url)}`,
   );
 
-  assert.typeof(
-    location,
-    'string',
-    `${path}.location in ${q(url)} must be string, got ${q(location)}`,
+  assertPackageLocation(location, `${keypath}.location`, url);
+  assertLabel(label, `${keypath}.label`, url);
+  assertScopes(scopes, `${keypath}.scopes`, url, assertFileUrlString);
+};
+
+/**
+ *
+ * @param {unknown} allegedCompartment
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts allegedCompartment is DigestedCompartmentDescriptor}
+ */
+const assertDigestedCompartmentDescriptor = (
+  allegedCompartment,
+  keypath,
+  url,
+) => {
+  assertCompartmentDescriptor(
+    allegedCompartment,
+    keypath,
+    url,
+    assertDigestedModuleConfigurations,
   );
-  assert.typeof(
-    name,
-    'string',
-    `${path}.name in ${q(url)} must be string, got ${q(name)}`,
+
+  const {
+    name: _name,
+    label: _label,
+    modules: _modules,
+    policy: _policy,
+    location: _location,
+    ...extra
+  } = allegedCompartment;
+
+  assertEmptyObject(
+    extra,
+    `${keypath} must not have extra properties; got ${q(
+      keys(extra),
+    )} in ${q(url)}`,
   );
-  assert.typeof(
+};
+
+/**
+ * @param {unknown} allegedCompartment
+ * @param {string} keypath
+ * @param {string} url
+ * @returns {asserts allegedCompartment is FileCompartmentDescriptor}
+ */
+const assertFileCompartmentDescriptor = (allegedCompartment, keypath, url) => {
+  assertCompartmentDescriptor(
+    allegedCompartment,
+    keypath,
+    url,
+    assertFileModuleConfigurations,
+  );
+
+  const {
+    location: _location,
+    name: _name,
     label,
-    'string',
-    `${path}.label in ${q(url)} must be string, got ${q(label)}`,
+    modules: _modules,
+    policy: _policy,
+    ...extra
+  } = /** @type {FileCompartmentDescriptor} */ (allegedCompartment);
+
+  assertEmptyObject(
+    extra,
+    `${keypath} must not have extra properties; got ${q(
+      keys(extra),
+    )} in ${q(url)}`,
   );
 
-  assertModules(modules, path, url);
-  assertParsers(parsers, path, url);
-  assertScopes(scopes, path, url);
-  assertTypes(types, path, url);
-  assertPolicy(policy, path, url);
+  assertString(label, `${keypath}.label`, url);
 };
 
 /**
  * @param {unknown} allegedCompartments
  * @param {string} url
+ * @returns {asserts allegedCompartments is Record<string, unknown>}
  */
-const assertCompartments = (allegedCompartments, url) => {
-  const compartments = Object(allegedCompartments);
+const assertCompartmentDescriptors = (allegedCompartments, url) => {
+  assertPlainObject(allegedCompartments, 'compartments', url);
+  const compartmentNames = keys(allegedCompartments);
   assert(
-    allegedCompartments === compartments || !Array.isArray(compartments),
-    `compartments must be an object, got ${q(allegedCompartments)} in ${q(
-      url,
-    )}`,
+    compartmentNames.length > 0,
+    `compartments must not be empty in ${q(url)}`,
   );
-  for (const [key, value] of Object.entries(compartments)) {
-    assertCompartment(value, `compartments[${q(key)}]`, url);
+  for (const key of keys(allegedCompartments)) {
+    assertString(
+      key,
+      `all keys of compartments must be strings; got ${key} in ${q(url)}`,
+    );
+  }
+  assert(
+    compartmentNames.every(name => typeof name === 'string'),
+    `all keys of compartments must be strings; got ${q(compartmentNames)} in ${q(url)}`,
+  );
+};
+
+/**
+ * @param {unknown} allegedCompartments
+ * @param {string} url
+ * @returns {asserts allegedCompartments is Record<string, FileCompartmentDescriptor>}
+ */
+const assertFileCompartmentDescriptors = (allegedCompartments, url) => {
+  assertCompartmentDescriptors(allegedCompartments, url);
+  for (const [key, value] of entries(allegedCompartments)) {
+    assertFileCompartmentDescriptor(value, `compartments[${q(key)}]`, url);
   }
 };
 
+/**
+ * @param {unknown} allegedCompartments
+ * @param {string} url
+ * @returns {asserts allegedCompartments is Record<string, PackageCompartmentDescriptor>}
+ */
+const assertPackageCompartmentDescriptors = (allegedCompartments, url) => {
+  assertCompartmentDescriptors(allegedCompartments, url);
+  for (const [key, value] of entries(allegedCompartments)) {
+    assertPackageCompartmentDescriptor(value, `compartments[${q(key)}]`, url);
+  }
+};
 /**
  * @param {unknown} allegedEntry
  * @param {string} url
+ * @returns {asserts allegedEntry is EntryDescriptor}
  */
 const assertEntry = (allegedEntry, url) => {
-  const entry = Object(allegedEntry);
-  assert(
-    allegedEntry === entry && !Array.isArray(entry),
-    `"entry" must be an object in compartment map, got ${allegedEntry} in ${q(
-      url,
-    )}`,
-  );
-  const { compartment, module, ...extra } = entry;
+  assertPlainObject(allegedEntry, 'entry', url);
+  const { compartment, module, ...extra } = allegedEntry;
   assertEmptyObject(
     extra,
-    `"entry" must not have extra properties in compartment map, got ${q(
-      Object.keys(extra),
+    `"entry" must not have extra properties in compartment map; got ${q(
+      keys(extra),
     )} in ${q(url)}`,
   );
-  assert.typeof(
-    compartment,
-    'string',
-    `entry.compartment must be a string in compartment map, got ${compartment} in ${q(
-      url,
-    )}`,
-  );
-  assert.typeof(
-    module,
-    'string',
-    `entry.module must be a string in compartment map, got ${module} in ${q(
-      url,
-    )}`,
-  );
+  assertString(compartment, 'entry.compartment', url);
+  assertString(module, 'entry.module', url);
 };
 
 /**
  * @param {unknown} allegedCompartmentMap
- * @param {string} [url]
+ * @param {string} url
  * @returns {asserts allegedCompartmentMap is CompartmentMapDescriptor}
  */
-
-export const assertCompartmentMap = (
-  allegedCompartmentMap,
-  url = '<unknown-compartment-map.json>',
-) => {
-  const compartmentMap = Object(allegedCompartmentMap);
-  assert(
-    allegedCompartmentMap === compartmentMap && !Array.isArray(compartmentMap),
-    `Compartment map must be an object, got ${allegedCompartmentMap} in ${q(
-      url,
-    )}`,
-  );
+const assertCompartmentMap = (allegedCompartmentMap, url) => {
+  assertPlainObject(allegedCompartmentMap, 'compartment map', url);
   const {
     // TODO migrate tags to conditions
     // https://github.com/endojs/endo/issues/2388
     tags: conditions,
     entry,
-    compartments,
+    compartments: _compartments,
     ...extra
-  } = Object(compartmentMap);
+  } = allegedCompartmentMap;
   assertEmptyObject(
     extra,
-    `Compartment map must not have extra properties, got ${q(
-      Object.keys(extra),
+    `Compartment map must not have extra properties; got ${q(
+      keys(extra),
     )} in ${q(url)}`,
   );
   assertConditions(conditions, url);
   assertEntry(entry, url);
-  assertCompartments(compartments, url);
+  assertTruthy(
+    allegedCompartmentMap.compartments?.[entry.compartment],
+    `compartments must contain entry compartment "${entry.compartment}" in ${q(url)}`,
+  );
+};
+
+/**
+ * @param {unknown} allegedCompartmentMap
+ * @param {string} [url]
+ * @returns {asserts allegedCompartmentMap is FileCompartmentMapDescriptor}
+ */
+export const assertFileCompartmentMap = (
+  allegedCompartmentMap,
+  url = '<unknown-compartment-map.json>',
+) => {
+  assertCompartmentMap(allegedCompartmentMap, url);
+  const { compartments } = allegedCompartmentMap;
+  assertFileCompartmentDescriptors(compartments, url);
+};
+
+/**
+ *
+ * @param {unknown} allegedCompartments
+ * @param {string} url
+ * @returns {asserts allegedCompartments is Record<string, DigestedCompartmentDescriptor>}
+ */
+export const assertDigestedCompartmentDescriptors = (
+  allegedCompartments,
+  url = '<unknown-compartment-map.json>',
+) => {
+  assertCompartmentDescriptors(allegedCompartments, url);
+  for (const [key, value] of entries(allegedCompartments)) {
+    assertDigestedCompartmentDescriptor(value, `compartments[${q(key)}]`, url);
+  }
+};
+
+/**
+ *
+ * @param {unknown} allegedCompartmentMap
+ * @param {string} [url]
+ * @returns {asserts allegedCompartmentMap is DigestedCompartmentMapDescriptor}
+ */
+export const assertDigestedCompartmentMap = (
+  allegedCompartmentMap,
+  url = '<unknown-compartment-map.json>',
+) => {
+  assertCompartmentMap(allegedCompartmentMap, url);
+  const { compartments } = allegedCompartmentMap;
+  assertDigestedCompartmentDescriptors(compartments, url);
+};
+
+/**
+ * @param {unknown} allegedCompartmentMap
+ * @param {string} [url]
+ * @returns {asserts allegedCompartmentMap is PackageCompartmentMapDescriptor}
+ */
+export const assertPackageCompartmentMap = (
+  allegedCompartmentMap,
+  url = '<unknown-compartment-map.json>',
+) => {
+  assertCompartmentMap(allegedCompartmentMap, url);
+  const { compartments } = allegedCompartmentMap;
+  assertPackageCompartmentDescriptors(compartments, url);
 };