feat(import): resolve references and schema composition

crates/crank-config/tests/contract.rs

@@ -108,9 +108,64 @@ fn source_for(
 }
 
 #[test]
-fn registry_covers_exactly_the_59_observed_runtime_names() {
+fn external_reference_contract_is_default_off_and_validates_prefixes_and_limits() {
+    let config = parse_process(
+        ProcessKind::AdminApi,
+        ConfigSource::from_utf8(required_admin()),
+    )
+    .expect("the external reference contract has safe defaults");
+    let references = &config.admin().unwrap().external_references;
+    assert!(references.allowed_url_prefixes.is_empty());
+    assert_eq!(references.max_depth, 8);
+    assert_eq!(references.max_documents, 32);
+    assert_eq!(references.max_fetch_bytes, 262_144);
+    assert_eq!(references.fetch_timeout_ms, 10_000);
+    assert_eq!(references.max_expanded_nodes, 10_000);
+
+    let mut allowed = required_admin();
+    allowed.insert(
+        "CRANK_IMPORT_EXTERNAL_REFERENCE_ALLOWED_URL_PREFIXES".to_owned(),
+        "https://schemas.example.test/openapi/,https://schemas.example.test/openapi/".to_owned(),
+    );
+    let config = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(allowed)).unwrap();
+    assert_eq!(
+        config
+            .admin()
+            .unwrap()
+            .external_references
+            .allowed_url_prefixes,
+        vec!["https://schemas.example.test/openapi/".to_owned()]
+    );
+
+    let mut invalid = required_admin();
+    invalid.insert(
+        "CRANK_IMPORT_EXTERNAL_REFERENCE_ALLOWED_URL_PREFIXES".to_owned(),
+        "https://user:secret@schemas.example.test/openapi/".to_owned(),
+    );
+    let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(invalid))
+        .expect_err("userinfo must never become an operator allow rule");
+    assert!(error.diagnostics().iter().any(|diagnostic| {
+        diagnostic.code == DiagnosticCode::InvalidType
+            && diagnostic.field == "import.external_references.allowed_url_prefixes"
+    }));
+
+    let mut out_of_range = required_admin();
+    out_of_range.insert(
+        "CRANK_IMPORT_EXTERNAL_REFERENCE_MAX_DOCUMENTS".to_owned(),
+        "33".to_owned(),
+    );
+    let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(out_of_range))
+        .expect_err("graph document limit must be bounded");
+    assert!(error.diagnostics().iter().any(|diagnostic| {
+        diagnostic.code == DiagnosticCode::OutOfRange
+            && diagnostic.field == "import.external_references.max_documents"
+    }));
+}
+
+#[test]
+fn registry_covers_exactly_the_65_observed_runtime_names() {
     let registry = field_registry();
-    assert_eq!(registry.len(), 59);
+    assert_eq!(registry.len(), 65);
     let unique = registry
         .iter()
         .map(|field| field.env_name)

crates/crank-config/tests/generation.rs

@@ -30,6 +30,9 @@ fn generated_reference_distinguishes_required_and_optional_fields() {
     assert!(reference.contains(
         "| `CRANK_LOG_LEVEL` | `observability.log_filter` | `Shared` | `string/-` | `blank` |"
     ));
+    assert!(reference.contains(
+        "| `CRANK_IMPORT_EXTERNAL_REFERENCE_ALLOWED_URL_PREFIXES` | `import.external_references.allowed_url_prefixes` | `AdminApi` | `url_prefix_list/-` | `` |"
+    ));
 }
 
 #[test]